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
|
Working on schroot -*- text -*-
==================
This document is a short guide to the conventions used in the schroot
project.
Building from git
-----------------
First, clone the git repositories:
% git clone git://anonscm.debian.org/git/buildd-tools/schroot
% cd schroot
% git remote add origin-dist git://anonscm.debian.org/git/buildd-tools/schroot-dist
% git fetch origin-dist
% ./bootstrap
schroot.dist is only required if you want to run "make dist-git"; this
repository is where the distribution branches are stored (from which
the distribution tarballs are created with "git archive"). See
"Releasing", below.
./bootstrap is required to bootstrap the autotools. Once this is done,
you can run ./configure just like from the release tarball.
Coding
------
The style should be apparent from the source. It is the default Emacs
c++-mode style, with paired brackets aligned vertically.
* Use 0 rather than NULL.
* Use C++ casts rather than C-style casts.
* Don't use void * unless there is no alternative.
* Add doxygen comments for everything; use EXTRACT_ALL = NO in
doc/schroot.dox to check for missing or incomplete documentation.
Format strings
--------------
The sources use boost::format for type-safe formatted output. Make
sure that the maximum number of options passed is the same as the
highest %n% in the format string.
The following styles are used
Style Formatting Syntax
--------------------------------------------------------------------
Values Single quotes '
Example text Double quotes \"
User input Double quotes \"
These are transformed into proper UTF-8 quotes with gettext.
Documentation
-------------
All the documentation is in UNIX manual page format. GNU roff
extensions are permitted, as is use of tbl. Make sure the printed
output is as good as terminal display. Run "make ps" or "make pdf" to
build the printed documentation.
The following styles are used:
Style Formatting Syntax
--------------------------------------------------------------------
New term Bold .B or \fB
Option definition Bold, args in italic .BR and \fI
Option reference Italic .I or \fI
File definition Bold italic \f[BI]
File reference Italic .I or \fI
Config key definition Courier bold italic \f[CBI]
Config key reference Courier italic \f[CI]
Values Single quotes \[oq] and \[cq]
Example text Double quotes \[lq] and \[rq]
Cross references Italics in double quotes \[lq]\fI...\fP\[rq]
Verbatim examples Courier \f[CR]
Verbatim user input Courier bold \f[CB]
Releasing
---------
The code must pass the testsuite:
% make check
It must also pass some tests which must be run by hand:
Chdir fallback behaviour:
Fallback behaviour has been documented in the manual pages.
Note that --debug=notice will show the internal fallback list
computed for the session.
Setup script behaviour:
To check if process termination works:
schroot -v -c sid -- sh -c "trap '' INT; trap '' TERM; sleep 2 &"
To check if process killing works:
schroot -v -c sid -- sh -c "trap '' INT; trap '' TERM; sleep 20 &"
In order to make a release, the following must be done:
* Use a fresh clone or make sure the tree is pristine, including
the debian directory (make sure it does not contain any build
material, which could be packaged if present).
* Make sure all generated files are up to date. Run "make dist"
and/or "make -C po update-po" to update all translations.
Commit any changes.
* Ensure that the distribution branch is branched locally. For
example, if making a 1.6.x release, checkout
origin-dist/distribution-1.6 as distribution-1.6 e.g.
% git checkout -b distribution-1.6 origin-dist/distribution-1.6
If this is the first release in a stable series, e.g. 1.6.0,
the local branch will be created automatically.
* Make the release:
% make release-git ENABLE_RELEASE_GIT=true
You will be prompted for your GPG key passphrase in order to
sign the release tag (release/schroot-$version).
* Rebootstrap and reconfigure:
% ./bootstrap
% ./config.status --recheck
% make
This will ensure the release metadata in VERSION is up to date (it's
generated from the release tag). Double check that there are no
modifed files. If there are, delete the release tag and start again.
* Make the distribution:
% make dist-git ENABLE_DIST_GIT=true
You will again be prompted for your GPG key passphrase, to sign the
distribution tag (distribution/schroot-$version). This will also
inject the distributed release onto the distribution-x.y branch.
Verify with "gitk distribution-x.y" that the distribution is sane,
and ties in sanely with the previous distributions and releases. If
there's a mistake, delete the distribution tag and reset --hard the
distribution-x.y branch to its previous state.
* Make the distributed release tarball:
git archive --format=tar --prefix=schroot-$version/ distribution/schroot-$version | xz --best > schroot-$version.tar.xz
This creates a tarball from the release tag.
* Push all branches and tags to the correct places:
% git push origin $branch
% git push origin release/schroot-$version
% git push origin-dist distribution-x.y
% git push origin-dist distribution/schroot-$version
|
