Importing a new upstream release from Ubuntu into Debian
========================================================

1. Download the upstream release tarball + signature, verify.
2. Get a local branch of Ubuntu packaging repo:
   http://bazaar.launchpad.net/~apparmor-dev/apparmor/apparmor-ubuntu-citrain/
3. Merge from that branch into our own Vcs-Bzr (see e.g. bzr revision
   1544 "Merge from ubuntu-citrain up to revision 1578" in Vcs-Bzr).
4. Handle merge conflits.
5. Commit.
6. Compare the tree with the content of the upstream tarball.
7. Update debian/changelog (see e.g. rev 1545..1547 in Vcs-Bzr).
8. Commit.
9. Build, test.
10. Upload and push to Vcs-Bzr.

Importing a new upstream release from the tarball
=================================================

1. Prepare the environment, e.g.:
   NEW_UPSTREAM_VERSION=2.11.0

2. Download the upstream release tarball and verify its signature:

       uscan --download

3. Extract the upstream tarball over the packaging repository:

       tar --strip-components=1 \
           -xf "../apparmor_${NEW_UPSTREAM_VERSION}.orig.tar.gz"

4. `bzr add' new files and `bzr rm' obsolete ones.

5. Compare the tree with the content of the upstream tarball, ignoring
   the `.bzr', `.pc' and `debian' directories:

       UNPACKED_NEW_UPSTREAM=$(mktemp -d)
       tar --strip-components=1 --directory="$UNPACKED_NEW_UPSTREAM" \
           -xf "../apparmor_${NEW_UPSTREAM_VERSION}.orig.tar.gz"
       diff -Naur --exclude .bzr --exclude .pc --exclude debian \
           "$UNPACKED_NEW_UPSTREAM" . \
           | diffstat

   There should be no difference. If it is not the case, adjust the tree
   to match the content of the upstream tarball; this generally boils down
   to `bzr rm'ing obsolete files. 

6. Commit:

       bzr commit --local -m "Import upstream ${NEW_UPSTREAM_VERSION} release."

7. Drop obsolete patches. Sometimes it's as simple as:

       grep --color=never -E '^r[0-9]+.*\.patch' debian/patches/series \
          | xargs -n 1 quilt delete \
          && bzr rm debian/patches/r[0-9]*.patch \
          && bzr commit --local debian/patches \
                        -m "Drop backported patches that are now obsolete."

8. Apply all quilt patches, update/refresh/delete them as needed.

9. Update debian/changelog:

       dch --newversion "${NEW_UPSTREAM_VERSION}-1" \
          && bzr commit --local debian/changelog \
                        -m "Update debian/changelog."

10. Build, test.

11. Upload and push to Vcs-Bzr.

