[[!meta title="Keyringer: development guidelines and workflow"]]

Index
-----

[[!toc levels=4]]

Development environment
-----------------------

The following steps needs to be run just once for each arch and distro version.

### Create the `debian/` structure

    if [ ! -d "debian" ]; then
      dh_make -p keyringer_0.1 --createorig
    fi

### Setup a sid pbuilder chroot

    DIST=sid git-pbuilder create

### Setup a sid cowbuilder chroot

    DIST=sid sudo cowbuilder --create

Environment maintenance
-----------------------

These steps should be run once in a while to ensure we have an up to date packaging environment.

### Pbuilder

    DIST=sid git-pbuilder update

### Cowbuilder

    DIST=sid sudo cowbuilder --update

Release workflow
----------------

Go to master branch

    git checkout master

Prepare the source code:

    $EDITOR keyringer # and update KEYRINGER_VERSION
    $EDITOR ChangeLog
    VERSION="`./keyringer | head -n 1 | cut -d ' ' -f 2`"

Create and upload a new release:

    make release

Update the debian branch:

    git checkout debian
    git-import-orig --upstream-vcs-tag=$VERSION ../tarballs/keyringer-$VERSION.tar.bz2
    dch -e # fine tune the changelog prepared by git-dch
    git commit -a -m "Updating debian/changelog"
    git tag -s debian_keyringer_$VERSION-1 -m "Keyringer debian package $VERSION-1"

Push everything:

    git push --tags

Build the package from the debian Git branch:

    git-buildpackage

Run lintian (or [add it to your pbuilder hooks](http://askubuntu.com/questions/140697/how-do-i-run-lintian-from-pbuilder-dist)):

    lintian --info --display-info --pedantic --color auto \
     ../build-area/keyringer_$VERSION*.changes

Create a signed tag in the debian branch:

    git-buildpackage --git-tag-only --git-sign-tags

Notes:

* `git-import-orig` takes care of running `pristine-tar commit`, of merging of the tag and orig tarball into the upstream branch, and then it merges the result into the debian branch. With the above configuration, it also runs git-dch to do the bulk of the work in `debian/changelog`.
* To build a development package, checkout the debian branch, merge master, run `git-dch --auto --snapshot` and build. 

Adding or changing a subcommand
-------------------------------

When adding a new subcommand or changing subcommand behavior, ensure:

* Documentation is updated.
* Manpage is updated.
* Shell completions are updated.

Test environment
----------------

Setup:

    keyringer test init ~/code/tests/keyringer

Teardown:

    rm -rf ~/code/tests/keyringer
    rm ~/.keyringer/test
    sed -i -e '/^test=/d' ~/.keyringer/config

Translation
-----------

Run just once:

    cd share/man
    po4a-gettextize -f text -m keyringer.1.mdwn -p keyringer.pot

References
----------

* [Using Git for Debian Packaging](http://www.eyrie.org/~eagle/notes/debian/git.html).
* [Building packages from the Git repository](http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.building.html).
* [Cowbuilder](https://wiki.debian.org/cowbuilder).
* [git-pbuilder](https://wiki.debian.org/git-pbuilder).
* [PackagingWithGit - Debian Wiki](https://wiki.debian.org/PackagingWithGit).
* [Generating pristine tarballs from git repositories](http://joeyh.name/blog/entry/generating_pristine_tarballs_from_git_repositories/).
* [Debian Packaging](https://wiki.debian.org/Packaging).
* [Debian Upstream Guide](https://wiki.debian.org/UpstreamGuide).