aboutsummaryrefslogtreecommitdiff
path: root/development.mdwn
blob: 67c64567b9509b05b42cc799405f53897c4f630f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
[[!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

Coding standards
----------------

  - Respect the existing coding style.

  - Be clear: easy audability must be one of keyringer's requirements.

Development workflow
--------------------

We use [git-flow](https://github.com/nvie/gitflow) for the development workflow.

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

Go to develop branch and start a new release

    git checkout develop
    git flow release start VERSION

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:

    git flow release finish $VERSION
    git checkout master
    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-buildpackage --git-tag-only --git-sign-tags

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

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:

    keyringer test teardown -y

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