# Updating the package

The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.

After you release a package, you will soon need to update it.

## New Debian revision

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

- If this is to be recorded as a new patch, do the following:

  - `dquilt new `bugname.patch`` to set the patch name;

  - `dquilt add `buggy-file`` to declare the file to be modified;

  - Correct the problem in the package source for the upstream bug;

  - `dquilt refresh` to record it to ``bugname.patch``;

  - `dquilt header -e` to add its description;

- If this is to update an existing patch, do the following:

  - `dquilt pop `foo.patch`` to recall the existing ``foo.patch``;

  - Correct the problem in the old ``foo.patch``;

  - `dquilt refresh` to update ``foo.patch``;

  - `dquilt header -e` to update its description;

  - `while dquilt push; do dquilt 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.

  To get the date in the required format, use `LANG=C date -R`.

- Include a short description of the bug and the solution in the changelog entry, followed by `Closes: #654321`. That way, the bug report will be automagically closed by the archive maintenance software the moment your package gets accepted into 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 completebuild and checkit.

- Once you are satisfied, you should change the distribution value in `changelog` from `UNRELEASED` to the target distribution value `unstable` (or even `experimental`).

  If you use the `dch -r` command to make this last change, please make sure to save the `changelog` file explicitly by the editor.

- Upload the package as in upload. 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.

One tricky case can occur when you make a local package, to experiment with the packaging before uploading the normal version to the official archive, e.g., ``1.0.1`-`1``. For smoother upgrades, it is a good idea to create a `changelog` entry with a version string such as ``1.0.1`-`1~rc1``. You may unclutter `changelog` by consolidating such local change entries into a single entry for the official package. See namever for the order of version strings.

## Inspection of the new upstream release

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

Start by reading the upstream `changelog`, `NEWS`, and whatever other documentation they may have released with the new version.

You can then inspect changes between the old and new upstream sources as follows, watching 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 delete them before running `diff` on the source for inspection.

## 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.

If a package ``foo`` is packaged in the old `1.0` format, this can be done by running `zcat /`path`/`to`/`foo`_`oldversion`.diff.gz|patch -p1` in the new extracted source, instead.

Of course, you need to do some obvious chores:

- Create a copy of the upstream source as the `foo_`newversion`.orig.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 by adding `Closes: #`bug_number``.

  - Describe concisely the changes to the new upstream release by the maintainer that fix reported bugs and close those bugs by adding `Closes: #`bug_number``.

- `while dquilt push; do dquilt 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 into the upstream source,

  - `dquilt delete` to remove it.

- If a patch you applied to the source conflicted with new changes in the upstream source,

  - `dquilt push -f` to apply old patches while forcing rejects as ``baz`.rej`.

  - Edit the ``baz`` file manually to bring about the intended effect of ``baz`.rej`.

  - `dquilt refresh` to update the patch.

- Continue as usual with `while dquilt push; do dquilt 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 dquilt push; do dquilt refresh; done
    $ dch
    ... document changes made

If you set up a `debian/watch` file as described in watch, 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.

If the `uscan` command downloads the updated source but it does not run the `uupdate` command, you should correct the `debian/watch` file to have `debian uupdate` at the end of the URL.

You can release this updated source by repeating what you did in completebuild, checkit, and upload.

## Updating the packaging style

Updating the package style is not a required activity for the update of a package. However, doing so lets you use the full capabilities of the modern `debhelper` system and the `3.0` source format.

If your sponsor or other maintainers object to updating the existing packaging style, don't bother arguing. There are more important things to do.

- If you need to recreate deleted template files for any reason, you can run `dh_make` again in the same Debian package source tree with the `--addmissing` option. Then edit them appropriately.

- If the package has not been 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 the following to understand its `DEB_*` configuration variables.

  - local copy of `&cdbs-doc;`

  - The Common Debian Build System (CDBS), FOSDEM 2009

- 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 the `debian/*` files can just be 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 the `debian/*` files can just be copied. Import the `big.diff` file generated by the command `filterdiff -z -x '*/debian/*' `foo`.diff.gz > big.diff` to your `quilt` system, if needed.

  You can split `big.diff` into many small incremental patches using the `splitdiff` command.

- If it was packaged using another patch system such as `dpatch`, `dbs`, or `cdbs` with `-p0`, `-p1`, or `-p2`, convert it to `quilt` using `deb3` at .

- 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 these and make it use the newer `3.0 (quilt)` source format.

You should check DEP - Debian Enhancement Proposals and adopt ACCEPTED proposals.

You need to do the other tasks described in newupstream, too.

## UTF-8 conversion

If upstream documents are encoded in old encoding schemes, converting them to UTF-8 is a good idea.

- Use

  iconv

  1 to convert encodings of plain text files.

      iconv -f latin1 -t utf8 foo_in.txt > foo_out.txt

- Use

  w3m

  1 to convert from HTML files to UTF-8 plain text files. When you do this, make sure to execute it under UTF-8 locale.

      LC_ALL=en_US.UTF-8 w3m -o display_charset=UTF-8 \
              -cols 70 -dump -no-graph -T text/html \
              < foo_in.html > foo_out.txt

## Reminders for updating packages

Here are a few reminders for updating packages:

- Preserve old `changelog` entries (sounds obvious, but there have been cases of people typing `dch` when they 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 the Debian Bug Tracking System (BTS) to see if someone has provided patches to bugs that are currently open.

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