[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ next ]

Debian New Maintainers' Guide
Chapter 9 - Updating the package

Once you release a package, you need to update it soon.

9.1 New Debian revision

Let's say that a bug report was filed against your package as #54321, and it describes a problem that you can solve. To create a new Debian revision of the package, you need to:

If this is to be recorded as a new patch, do the following.
- "quilt new bugname.patch" to set patch name;
- "quilt add buggy-file" to declare file to be modified;
- Correct the problem in the package source for the upstream bug;
- "quilt refresh" to record to bugname.patch;
- "quilt header -e" to add its description;

If this is to update an existing patch, do the following.
- "quilt pop foo.patch" to recall existing foo.patch;
- Correct the problem in the old foo.patch;
- "quilt refresh" to update foo.patch;
- "quilt header -e" to update its description;
- "while quilt push; do quilt refresh; done" to apply all patches while removing fuzz;

Add a new revision at the top of the Debian changelog file, for example with "dch -i", or explicitly with "dch -v version-revision" and then insert the comments using your preferred editor. [53]

Include a short description of the bug and the solution in the changelog entry, followed by "Closes: #54321". That way, the bug report will be automagically closed by the archive maintenance software the moment your package gets accepted in the Debian archive.

Repeat what you did in the above to fix more bugs while updating the Debian changelog file with "dch" as needed.

Repeat what you did in Complete (re)build, Section 6.1, Checking the package for errors, Chapter 7, and Uploading the package, Chapter 8. The difference is that this time, the original source archive won't be included, as it hasn't been changed and it already exists in the Debian archive.

9.2 Inspection of the new upstream release

When preparing packages of the new upstream release for the Debian archive, you must check the new upstream release, first.

You start this by reading the upstream changelog, NEWS, and whatever other documentations they may have released with the new version.

You then inspect changes between the old and new upstream sources as follow to watch out for anything suspicious.

     $ diff -urN foo-oldversion foo-newversion

Changes to some auto-generated files by Autotools such as missing, aclocal.m4, config.guess, config.h.in, config.sub, configure, depcomp, install-sh, ltmain.sh, and Makefile.in may be ignored. You may erase them before running diff to the source for inspection.

9.3 New upstream release

If a package foo is properly packaged in the newer 3.0 (native) or 3.0 (quilt) formats, packaging a new upstream version is essentially moving the old debian directory to the new source. This can be done by running "tar xvzf /path/to/foo_oldversion.debian.tar.gz" in the new extracted source. [54] Of course, you need to do few obvious chores.

Create a copy of upstream source as the foo_newversion.tar.gz file.

Update the Debian changelog file with "dch -v newversion-1".
- Add an entry with "New upstream release".
- Describe concisely the changes in the new upstream release that fix reported bugs and close those bugs.
- Describe concisely the changes to the new upstream release by the maintainer that fix reported bugs and close those bugs.

"while quilt push; do quilt refresh; done" to apply all patches while removing fuzz.

If the patch/merge did not apply cleanly, inspect the situation (clues are left in .rej files).

If a patch you applied to the source was integrated to the upstream source,
- "quilt delete" to remove it.

If a patch you applied to the source conflicted with new changes in the upstream source,
- "quilt push -f" to apply old patches while forcing rejects as baz.rej.
- Edit the baz file manually to realize intended effect of baz.rej.
- "quilt refresh" to update the patch.

Continue back to "while quilt push; do quilt refresh; done".

This process can be automated using the uupdate(1) command as follows:

     $ apt-get source foo
     ...
     dpkg-source: info: extracting foo in foo-oldversion
     dpkg-source: info: unpacking foo_oldversion.orig.tar.gz
     dpkg-source: info: applying foo_oldversion-1.debian.tar.gz
     $ ls -F
     foo-oldversion/
     foo_oldversion-1.debian.tar.gz
     foo_oldversion-1.dsc
     foo_oldversion.orig.tar.gz
     $ wget http://example.org/foo/foo-newversion.tar.gz
     $ cd foo-oldversion
     $ uupdate -v newversion ../foo-newversion.tar.gz
     $ cd ../foo-newversion
     $ while quilt push; do quilt refresh; done
     $ dch
     ... document changes made

If you set up a debian/watch file as described in watch file, Section 5.20, you can skip the wget command. You simply run uscan(1) in the foo-oldversion directory instead of the uupdate command. This will automagically look for the updated source, download it, and run the uupdate command. [55]

You can release this updated source by repeating what you did in Complete (re)build, Section 6.1, Checking the package for errors, Chapter 7, and Uploading the package, Chapter 8.

9.4 Updating the packaging style

Updating the package style is not a required activity for the update of a package. But, you can use the full capability of the modern debhelper system and the 3.0 source format by doing this. [56]

If you need to add erased template files for any reason, you may run dh_make again in the same Debian package source tree with --addmissing option. Then edit them properly.

If the package has not updated to use the debhelper V7 dh syntax for the debian/rules file, update it to use dh. Update the debian/control file accordingly.

If you want to update the rules file created with the Makefile inclusion mechanism of the Common Debian Build System (cdbs) to the dh syntax, see /usr/share/doc/cdbs/cdbs-doc.html and understand its DEB_* configuration variables. [57]

If you have a 1.0 source package without the foo.diff.gz file, you can update it to the newer 3.0 (native) source format by creating debian/source/format with "3.0 (native)". The rest of debian/* files can be just copied.

If you have a 1.0 source package with the foo.diff.gz file, you can update it to the newer 3.0 (quilt) source format by creating debian/source/format with "3.0 (quilt)". The rest of debian/* files can be just copied. Import the big.diff file generated by the "filterdiff -z -x '*/debian/*' foo.diff.gz > big.diff" command to your quilt system, if needed. [58]

If it was packaged with another patch system such as dpatch, dbs, or cdbs with -p0, -p1, or -p2, convert it to the quilt command using deb3 at http://bugs.debian.org/581186.

If it was packaged with the dh command with the "--with quilt" option or with the dh_quilt_patch and dh_quilt_unpatch commands, remove such things and make it use the newer 3.0 (native) source format.

You need to do other tasks described in New upstream release, Section 9.3, too.

9.5 Reminders for updating packages

Here are few reminders for updating packages.

Preserve old changelog entries (sounds obvious, but there have been incidents to type "dch" when you should have typed "dch -i".)

Existing Debian changes need to be reevaluated; throw away stuff that upstream has incorporated (in one form or another) and remember to keep stuff that hasn't been incorporated by upstream, unless there is a compelling reason not to.

If any changes were made to the build system (hopefully you'd know from inspecting upstream changes) then update the debian/rules and debian/control build dependencies if necessary.

Check to see Debian Bug Tracking System (BTS) if someone have provided patches to bugs that are currently open in it.

Check the contents of the .changes file to make sure you are uploading to the correct distribution, the proper bugs closures are listed in the Closes field, the Maintainer and Changed-By fields match, the file is GPG-signed, etc.