4 Author: Manoj Srivastava And Russ Allbery
5 Date: 2010-06-04 09:42:57 PDT
11 + Website:: [http://www.debian.org/doc/devel-manuals#policy]
12 + Mailing list:: debian-policy@lists.debian.org lists
14 * git clone git://git.debian.org/git/dbnpolicy/policy.git
15 * Browser: [http://git.debian.org/?p=dbnpolicy/policy.git]
16 + Unix group:: dbnpolicy
17 + Alioth Project:: [http://alioth.debian.org/projects/dbnpolicy] (exists
18 to manage the repository but not otherwise used)
20 Interacting with the team
21 ==========================
23 + Email contact:: [mailto:debian-policy@lists.debian.org]
24 + Request tracker:: [http://bugs.debian.org/src:debian-policy]
26 Debian Policy uses a formal procedure and a set of user tags to manage
27 the lifecycle of change proposals. For definitions of those tags and
28 proposal states and information about what the next step is for each
29 phase, see [Policy changes process].
31 Once the wording for a change has been finalized, please send a patch
32 against the current Git master branch to the bug report, if you're not
33 familiar with Git, the following commands are the basic process:
36 git clone git://git.debian.org/git/dbnpolicy/policy.git
37 git checkout -b <local-branch-name>
39 # edit files, but don't make changes to upgrading-checklist or debian/changelog
44 # update your branch against the current master
49 git merge --no-commit <local-branch-name>
50 git reset --hard HEAD;
51 git checkout <local-branch-name>;
53 # If there are changes in master that make the branch not apply cleanly, there
54 # should have been en error during the merge step above. If there was an
55 # error, merge the master branch into the local branch, fix the conflicts, and
56 # commit the new version of the local branch.
58 # Edit files to remove conflict
61 # Checkout the local branch, to create the patch to send to the policy
62 git checkout <local-branch-name>
64 git format-patch -o $dir -s master
65 # check out the patches created in $dir
66 git send-email --from "you <your@email>" \
67 --to debian-policy@lists.debian.org \
70 <local-branch-name> is some convenient name designating your local
71 changes. You may want to use some common prefix like local-. You can
72 use git format-patch and git send-email if you want, but usually it's
76 [Policy changes process]: Process.txt
81 The Debian Policy team are official project delegates (see the DPL
82 delegation). All of the Policy team members do basically the same
83 work: shepherd proposals, propose wording, and merge changes when
84 consensus has been reached. The current delegates are:
90 + Colin Watson (cjwatson)
92 The special tasks of Policy delegates are:
94 + Commit access to the Git repository and uploads of the debian-policy
95 package itself, which makes them responsible for debian-policy as a
96 package in Debian and for making final decisions about when a new
97 version is released and what bits go into it.
98 + Rejecting proposals. Anyone can argue against a proposal, but only
99 Policy delegates can formally reject it.
100 + Counting seconds and weighing objections to proposals to determine
101 whether the proposal has sufficient support to be included.
103 Everything else can be done by anyone, or any DD (depending on the
104 outcome of the discussion about seconding). We explicitly want any
105 Debian DD to review and second or object to proposals. The more
106 participation, the better. Many other people are active on the Policy
107 mailing list without being project delegates.
112 The Debian Policy team is responsible for maintaining and coordinating
113 updates to the technical Policy manuals for the project. The primary
114 output of the team is the Debian Policy Manual and the assorted
115 subpolicies, released as the debian-policy Debian package and also
116 published at [http://www.debian.org/doc/].
118 In addition to the main technical manual, the team currently also maintains:
120 + [Debian Menu sub-policy]
121 + [Debian Perl Policy]
122 + [Debian MIME support sub-policy]
123 + [Debconf Specification]
124 + [Authoritative list of virtual package names ]
126 These documents are maintained using the [Policy changes process], and
127 the current state of all change proposals is tracked using the
131 [Debian Menu sub-policy]: http://www.debian.org/doc/packaging-manuals/menu-policy/
132 [Debian Perl Policy]: http://www.debian.org/doc/packaging-manuals/perl-policy/
133 [Debian MIME support sub-policy]: http://www.debian.org/doc/packaging-manuals/mime-policy/
134 [Debconf Specification]: http://www.debian.org/doc/packaging-manuals/debconf_specification.html
135 [Authoritative list of virtual package names ]: http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt
136 [Policy changes process]: Process.txt
137 [debian-policy BTS]: http://bugs.debian.org/src:debian-policy
142 The best way to help is to review the [current open bugs], pick a bug
143 that no one is currently shepherding (ask on
144 [debian-policy@lists.debian.org] if you're not sure if a particular bug
145 is being shepherded), and help it through the change process. This
146 will involve guiding the discussion, seeking additional input
147 (particularly from experts in the area being discussed), possibly
148 raising the issue on other mailing lists, proposing or getting other
149 people to propose specific wording changes, and writing diffs against
150 the current Policy document. All of the steps of [Policy changes process]
151 can be done by people other than Policy team members except
152 the final acceptance steps and almost every change can be worked on
153 independently, so there's a lot of opportunity for people to help.
155 There are also some other, larger projects:
157 + Policy is currently maintained in DebianDoc-SGML, which is no longer
158 very actively maintained and isn't a widely used or understood
159 format. The most logical replacement would be DocBook. However,
160 DocBook is a huge language with many tags and options, making it
161 rather overwhelming. We badly need someone with DocBook experience
162 to write a style guide specifying exactly which tags should be used
163 and what they should be used for so that we can limit ourselves to
164 an easy-to-understand and documented subset of the language.
165 + Policy contains several appendices which are really documentation of
166 how parts of the dpkg system works rather than technical
167 Policy. Those appendices should be removed from the Policy document
168 and maintained elsewhere, probably as part of dpkg, and any Policy
169 statements in them moved into the main document. This project will
170 require reviewing the current contents of the appendices and feeding
171 the useful bits that aren't currently documented back to the dpkg
172 team as documentation patches.
173 + Policy has grown organically over the years and suffers from
174 organizational issues because of it. It also doesn't make use of the
175 abilities that a current XML language might give us, such as being
176 able to extract useful portions of the document (all *must*
177 directives, for example). There has been quite a bit of discussion
178 of a new format that would allow for this, probably as part of
179 switching to DocBook, but as yet such a reorganization and reworking
180 has not been started.
182 If you want to work on any of these projects, please mail
183 [debian-policy@lists.debian.org ] for more information. We'll be happy to
184 help you get started.
187 [current open bugs]: http://bugs.debian.org/src:debian-policy
188 [debian-policy@lists.debian.org]: mailto:debian-policy@lists.debian.org
189 [Policy changes process]: Process.txt
190 [debian-policy@lists.debian.org ]: mailto:debian-policy@lists.debian.org
192 Maintenance procedures
193 =======================
198 The Git repository used for Debian Policy has the following branches:
200 + master:: the current accepted changes that will be in the next release
201 + bug<number>-<user>:: changes addressing bug <number>, shepherded by <user>
202 + rra:: old history of Russ's arch repository, now frozen
203 + srivasta:: old history of Manoj's arch repository
208 The process used by Policy team members to manage a bug, once there is
209 proposed wording, is:
211 + Create a bug<number>-<user> branch for the bug, where <number> is
212 the bug number in the BTS and <user> is a designator of the Policy
213 team member who is shepherding the bug.
214 + Commit wording changes in that branch until consensus is
215 achieved. Do not modify debian/changelog or upgrading-checklist.html
216 during this phase. Use the BTS to track who proposed the wording and
218 + git pull master to make sure you have the latest version.
219 + Once the change has been approved by enough people, git merge the
220 branch into master immediately after making the final commit adding
221 the changelog entry to minimize conflicts.
222 + add the debian/changelog and upgrading-checklist.html changes, and
224 + Push master out so other people may merge in their own bug branches
226 + Tag the bug as pending and remove other process tags.
227 + Delete the now-merged branch.
229 The Git commands used for this workflow are:
231 git checkout -b bug12345-rra master
235 git push origin bug12345-rra
237 # update your local master branch
242 git merge --no-commit bug12345-rra
243 git reset --hard HEAD;
245 # If there are changes in master that make the branch not apply cleanly, there
246 # should have been en error during the merge step above. If there was an
247 # error, merge the master branch into the local branch, fix the conflicts, and
248 # commit the new version of the local branch.
249 git checkout bug12345-rra
251 # Edit files to remove conflict
255 git merge bug12345-rra
256 # edit debian/changelog and upgrading-checklist.html
257 git add debian/changelog upgrading-checklist.html
259 git push origin master
260 git branch -d bug12345-rra
261 git push origin :bug12345-rra
263 For the debian/changelog entry, use the following format:
265 * <document>: <brief change description>
266 Wording: <author of wording>
269 Closes: <bug numbers>
273 * Policy: better document version ranking and empty Debian revisions
274 Wording: Russ Allbery <rra@debian.org>
275 Seconded: Raphaƫl Hertzog <hertzog@debian.org>
276 Seconded: Manoj Srivastava <srivasta@debian.org>
277 Seconded: Guillem Jover <guillem@debian.org>
278 Closes: #186700, #458910
283 After commits to master have been pushed, either by you or by another
284 Policy team member, you will generally want to update your working bug
285 branches. The equivalent of the following commands should do that:
288 for i in `git show-ref --heads | awk '{print $2}'`; do
290 if [ "$j" != "master" ]; then
291 git checkout $j && git merge master
294 git push --all origin
296 assuming that you haven't packed the refs in your repository.
301 For a final Policy release, change UNRELEASED to unstable in
302 debian/changelog and update the timestamp to match the final release
303 time (dch -r may be helpful for this), update the release date in
304 upgrading-checklist.html, update Standards-Version in debian/control,
305 and commit that change. Then do the final release build and make sure
306 that it builds and installs.
308 Then, tag the repository and push the final changes to Alioth:
313 git push --tags origin
315 replacing the version number with the version of the release, of course.
317 Finally, announce the new Policy release on debian-devel-announce,
318 including in the announcement the upgrading-checklist section for the
321 Setting release goals
322 ======================
324 Policy has a large bug backlog, and each bug against Policy tends to
325 take considerable time and discussion to resolve. I've found it
326 useful, when trying to find a place to start, to pick a manageable set
327 of bugs and set as a target resolving them completely before the next
328 Policy release. Resolving a bug means one of the following:
330 + Proposing new language to address the bug that's seconded and approved by
331 the readers of the Policy list following the [Policy changes process] (or
332 that's accepted by one of the Policy delegates if the change isn't
333 normative; i.e., doesn't change the technical meaning of the document).
334 + Determining that the bug is not relevant to Policy and closing it.
335 + Determining that either there is no consensus that the bug indicates
336 a problem, that the solutions that we can currently come up with are
337 good solutions, or that Debian is ready for the change. These bugs
338 are tagged wontfix and then closed after a while. A lot of Policy
339 bugs fall into this category; just because it would be useful to
340 have a policy in some area doesn't mean that we're ready to make
341 one, and keeping the bugs open against Policy makes it difficult to
342 tell what requires work. If the problem is worth writing a policy
343 for, it will come up again later when hopefully the project
344 consensus is more mature.
346 Anyone can pick bugs and work resolve them. The final determination to
347 accept a wording change or reject a bug will be made by a Policy
348 delegate, but if a patch is already written and seconded, or if a
349 summary of why a bug is not ready to be acted on is already written,
350 the work is much easier for the Policy delegate.
352 One of the best ways to help out is to pick one or two bugs (checking
353 on the Policy list first), say that you'll make resolving them a goal
354 for the next release, and guide the discussion until the bugs can
355 reach one of the resolution states above.
357 [Policy changes process]: ./Progress.org