File: README.source

package info (click to toggle)
munin 2.999.14-1
  • links: PTS, VCS
  • area: main
  • in suites: experimental
  • size: 10,036 kB
  • sloc: perl: 31,052; sh: 12,473; java: 1,924; python: 852; makefile: 336; ruby: 232; awk: 169; xml: 45; sql: 11
file content (183 lines) | stat: -rw-r--r-- 5,296 bytes parent folder | download
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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
=======================
 Munin packaging guide
=======================

This is a rough guide for the munin packaging in Debian. The tool used
is «gbp», which is found in the «git-buildpackage» package.

TL;DR
=====

For the impatient, here's a quick recipe for importing a new release::

  new_version=2.0.21

  # fetch any remote updates
  gbp pull

  # import new upstream release
  gbp import-orig --uscan --upstream-vcs-tag=$new_version
  dch -v ${new_version}-1 Imported new upstream release ${new_version}
  git add debian/changelog
  debcommit

  # push new upstream release to packaging repository
  git push origin debian upstream upstream/${new_version}

Then: refresh patches (if any), build, test, release, and upload.

Git branches
============

The git repository branches used by packaging are:

* debian - packaging branch for «unstable». All new releases going to
  unstable → testing → stable goes here.

* upstream - branch for importing the upstream releases.

* pristine-tar - branch for the tarball deltas. The content of this
  branch is one (hopefully small) file containing the differences
  between a tarball and a release tag.

If we have releases in «experimental», a pair of branches is used for
that:

* debian-experimental - packaging branch for experimental releases.

* upstream-experimental - upstream branch for experimental releases.

If we have to make security releases, they should go into branches
named debian-$release and upstream-$release. Example for the "jessie"
release:

* debian-jessie - packaging branch for updates to the packages in
  jessie. Typically used for security releases, and hopefully not
  needed.

* upstream-jessie - upstream release branch used by debian-jessie.


Importing a new upstream versions
=================================

The upstream release tarballs are signed. They should be downloaded,
verified, and added to the «pristine-tar» branch.

Using "gbp import-orig"::

  # Import, tag and merge
  git remote update
  gbp import-orig --uscan --upstream-vcs-tag=2.0.21

For the upstream-vcs-tag to work, you will need to have the upstream
repository as a remote to the packaging repository.  The upstream
release tag must be known beforehand, and used on the command line.

This does:
* Import upstream tarball into «pristine-tar» branch

* Commit the the tarball contents to the «upstream»-branch, adding the
  upstream-vcs-tag as an extra parent to the commit. This links the
  upstream commit history to the tag in the «upstream» packaging
  branch.

Bump the version in debian/changelog::

  dch -v 2.0.21-1 Imported new upstream release 2.0.21
  git add debian/changelog
  debcommit

Handling patches
================

Debian specific patches reside in debian/patches/ and are applied with
quilt.

Adding or refreshing the patches can be done with "gbp pq"
(git-buildpackage patch-queue)::

  # after new release, import or rebase patches from quilt into local branch
  gbp pq import # if you do not have a patch branch already.
                # Otherwise, do "gbp pq rebase".
                # You will be told about this. :)

  # make changes, commit to git
  $editor file/to/be/edited.pl
  git commit -m 'fix frobnication bug'

  # Use "git cherry-pick" to backport patches
  git cherry-pick $git_commit_id

  # export patches from local branch back to quilt
  gbp pq export

  # git add / rm, and commit changes made to debian/patches
  git commit -m 'Refresh patches'

Refreshing should be done after each new upstream release.

Backported patches included in the new release will be dropped when
using "gbp pq import", "gbp pq export" and "git commit -a -m 'refresh
patches' debian/patches"

Building the package
====================

Build with your favourite packaging tool. The packaging should be
compatible with most tools.

These all work:

* git-buildpackage
* gitpkg (makes a .dsc source package, which can be built with
  "sbuild" or "pbuilder")
* sbuild
* pbuilder
* debuild
* dpkg-buildpackage

Testing the package
===================

Munin has "DEP-8" tests. This means you can test the built packages to
see if they perform as expected.

To run the tests in a prepared schroot, assuming its name is
"autopkgtest-amd64"::

  # run from the root of the munin packaging directory:

  schroot_name=autopkgtest-amd64
  munin_changes=/path/to/munin-1.2.3-1_amd64.changes
  adt-run $(dcmd --deb $munin_changes) --built-tree=. --- adt-virt-schroot $schroot_name

…or in a hopefully not-too-distant future, when adt-run can extract
what it needs from source and binaries from the .changes file::

  adt-run --changes $munin_changes --- adt-virt-schroot $schroot_name

Releasing a package
===================

Before release, the changelog must be up to date. There is no need to
change debian/changelog for each commit.

* «gbp dch» - reads the git commit log, and writes to debian/changelog

* «dch» - edits debian/changelog

* «debcommit» - commits and tags.

Example::

  # Write changelog entries to debian/changelog
  gbp dch -a

  # Set the "release" to something else than UNRELEASED
  dch -r

  # Commit debian/changelog, and make a signed tag
  debcommit -r --sign-tags -- debian/changelog

 -- Stig Sandbeck Mathisen <ssm@fnord.no>, Sat, 26 Dec 2015 12:53:29 +0100