# Releases and Snapshots

The `debian/changelog` gives the Debian™ package a version number and keeps track of changes made to the package in a particular version. While the changelog can still be maintained by hand we can make use of gbp dch to have our Git™ commit messages end up in `debian/changelog`. This avoids the double maintenance of the Git™ commit history and the Debian™ changelog. If you don't want a one to one mapping of changelog entries to Git™ commits you're free to edit the changelog by hand at any point.

Not committing changelog entries with the actual modifications also has the advantage that the changelog won't cause any trouble when cherry-picking patches from different branches. It can be created when releasing the package or after performing several commits. Invocations of dch™ and gbp dch can be mixed.

## Maintaining `debian/changelog`

### Creating `debian/changelog` just before the release

The simplest way is doing all the changes to the `debian-branch` without touching `debian/changelog` at all. Then, when done, do:

    gbp dch --release

This will look up the latest released version in the changelog, increment the version in the Debian™ changelog, generate changelog messages from the corresponding Git™ commit id up to the branch head, and finally spawns an editor for final changelog editing.

### Incrementally filling `debian/changelog`

You can run gbp dch without any options to make it add all commit messages since the last Debian™ tag to a new UNRELEASED changelog section:

    gbp dch

You can then commit the `debian/changelog` to have your current changes recorded. Later invocations of gbp dch will check when `debian/changelog` was last modified and not add these commits again. Upon your last call of gbp dch before releasing the package add `--release` again to have the UNRELEASED distribution in the changelog turned into unstable.