Update docs

diff --git a/README.rst b/README.rst
index 385eaebd6c76dc85695e893727953b119ad80ba7..5e3fcd30106f7bb2e1f727cc452a125445be8c2d 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -56,6 +56,20 @@ on having to package all the dependencies of the newest version, you can::
   REALVER=<old-version> ./update.sh  <rust-crate-name>  # then
   REALVER=<old-version> ./release.sh <rust-crate-name>
 
+Repackaging the existing revision
+---------------------------------
+
+In order to build a package A already in ``debcargo-conf/src``
+in the exact version which is present here, do the following::
+
+  $ ./repackage.sh A
+  $ cd build
+  $ ./build.sh A
+
+If this package is already in the archive and you want to recreate that
+exactly, you will need to use the exact same version of debcargo that was
+used previously. This version is mentioned in ``debian/changelog``.
+
 
 Repository structure
 ====================
@@ -74,6 +88,37 @@ want to test your crate, instead run::
 omitting or not omitting the stuff in [] as needed.
 
 
+Build environment
+=================
+
+To set up a suitable build environment for ``./build.sh``::
+
+  $ sudo apt-get install devscripts reprepro debootstrap sbuild dh-cargo
+  $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \
+      --chroot-prefix debcargo-unstable unstable \
+      /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian
+
+Normally, ``./build.sh`` will fail early if not all the build dependencies are
+available in your local apt cache. If you are packaging a large dependency tree
+however, to avoid many round-trips through NEW it is possible to bypass this
+check and build all the packages together. Suppose package B depends on package
+A, then you can run something like::
+
+  $ export IGNORE_MISSING_BUILD_DEPS=1
+  $ ./release.sh A
+  $ ( cd build && ./build.sh A )
+  # push pending and checkout master
+  $ ./release.sh B
+  $ ( cd build && ./build.sh B librust-A*.deb )
+
+The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to
+sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have
+been built by the previous step.
+
+After everything is built successfully, you can ``dput`` all of them and then
+push all the ``pending-*`` branches as normal.
+
+
 General packaging tips
 ======================
 
@@ -188,47 +233,3 @@ code in a minor way to use the new crate API, then: for each crate that needs
 to be updated, you should instead name the patch ``update-dep-<crate>.patch``
 and add both the ``Cargo.toml`` and the source code changes to it. Use
 ``quilt rename`` if that helps you.
-
-
-DD instructions
-===============
-
-To set up a suitable build environment for ``./build.sh``::
-
-  $ sudo apt-get install devscripts reprepro debootstrap sbuild dh-cargo
-  $ sudo sbuild-createchroot --include=eatmydata,ccache,gnupg,dh-cargo,cargo,lintian,perl-openssl-defaults \
-      --chroot-prefix debcargo-unstable unstable \
-      /srv/chroot/debcargo-unstable-amd64-sbuild http://deb.debian.org/debian
-
-Normally, ``./build.sh`` will fail early if not all the build dependencies are
-available in your local apt cache. If you are packaging a large dependency tree
-however, to avoid many round-trips through NEW it is possible to bypass this
-check and build all the packages together. Suppose package B depends on package
-A, then you can run something like::
-
-  $ export IGNORE_MISSING_BUILD_DEPS=1
-  $ ./release.sh A
-  $ ( cd build && ./build.sh A )
-  # push pending and checkout master
-  $ ./release.sh B
-  $ ( cd build && ./build.sh B librust-A*.deb )
-
-The extra arguments after ``./build.sh B <args>`` is extra deb files to pass to
-sbuild to use as dependencies. In this case, ``librust-A*.deb`` should have
-been built by the previous step.
-
-After everything is built successfully, you can ``dput`` all of them and then
-push all the ``pending-*`` branches as normal.
-
-Packaging the existing revision
-===============================
-
-In order to build a package A already in ``debcargo-conf/src``
-in the exact version which is present here, do the following::
-
-  $ ./repackage.sh A
-  $ cd build
-  $ ./build.sh A
-
-If this package is already in the archive and you want to recreate that, you
-will need to use the exact same version of debcargo that was used previously.

diff --git a/release.sh b/release.sh
index 9cb2a8bfdaa6c3d0114b2fb11c19072f656852c0..00588b7f6ac158a6a7dd3aab345e6dc84fd480d7 100755 (executable)
--- a/release.sh
+++ b/release.sh
@@ -51,7 +51,10 @@ esac
 
 if head -n1 "$PKGDIR/debian/changelog" | grep -qv UNRELEASED-FIXME-AUTOGENERATED-DEBCARGO; then
        git checkout "$PREVBRANCH"
-       abort 0 "Package already released on branch $RELBRANCH. If that was a mistake then run:\ngit branch -D $RELBRANCH\nAnd re-run this script ($0 $*). You might have to delete the remote branch too:\ngit push --delete origin $RELBRANCH"
+       abort 0 "Package already released on branch $RELBRANCH. If that was a mistake then run:" \
+         "    git branch -D $RELBRANCH" \
+         "And re-run this script ($0 $*). You might have to delete the remote branch too:" \
+         "    git push --delete origin $RELBRANCH"
 fi
 
 ( cd "$PKGDIR"
@@ -115,8 +118,8 @@ recommended way is to run something like:
 
   cd build && ./build.sh $CRATE $VER && dput ${DEBSRC}_${DEBVER}_${DEB_HOST_ARCH}.changes
 
-This assumes you followed the "DD instructions" in README.rst, for setting up
-a build environment for release.
+This assumes you followed the "Build environment" instructions in README.rst,
+for setting up a build environment for release.
 
 If the build fails e.g. due to missing Build-Dependencies you should revert
 what I did (see below) and package those missing Build-Dependencies first.

diff --git a/update.sh b/update.sh
index 181663ced8f9d4c91f8e3af7c29d970541f55cae..c48f7e5347eb37e9159100004d64ec4b72da2794 100755 (executable)
--- a/update.sh
+++ b/update.sh
@@ -87,7 +87,7 @@ You can test-build your package by running:
 
   cd build && ./build.sh $CRATE $VER
 
-This assumes that you have set up sbuild; see "DD instructions" in README.rst
+This assumes that you have set up sbuild; see "Build environment" in README.rst
 for details. Try to fix any lintian errors, but note that some errors are due
 to lintian being out-of-date and/or are expected at this stage of the process
 (e.g. bad-distribution-in-changes-file). Ask on IRC when in doubt.