1 -*- mode: org; fill-column: 78 -*-
3 #+STARTUP: lognotedone lognotestate
6 #+AUTHOR: Manoj Srivastava And Russ Allbery
7 #+EMAIL: srivasta@debian.org
8 #+OPTIONS: H:3 num:nil toc:nil \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:nil skip:t d:nil tags:not-in-toc
9 #+LINK_HOME: http://wiki.debian.org/Teams/Policy
10 #+LINK_UP: http://www.debian.org/
12 \usepackage{landscape}
14 \setlength{\oddsidemargin}{0in} % default=0in
15 \setlength{\textwidth}{9in} % default=9in
17 \setlength{\columnsep}{0.5in} % default=10pt
18 \setlength{\columnseprule}{1pt} % default=0pt (no line)
20 \setlength{\textheight}{5.85in} % default=5.15in
21 \setlength{\topmargin}{-0.15in} % default=0.20in
22 \setlength{\headsep}{0.25in} % default=0.35in
24 \setlength{\parskip}{1.2ex}
25 \setlength{\parindent}{0mm}
28 \setlength{\headheight}{0pt}
29 \setlength{\headsep}{0pt}
30 \setlength{\footskip}{5pt}
31 \setlength{\textheight}{9.0in}
32 \setlength{\textwidth}{6.5in}
37 + Website:: http://www.debian.org/doc/devel-manuals#policy
38 + Mailing list:: debian-policy@lists.debian.org lists
40 * git clone git://anonscm.debian.org/dbnpolicy/policy.git
41 * Browser: http://anonscm.debian.org/gitweb/?p=dbnpolicy/policy.git
42 + Unix group:: dbnpolicy
43 + Alioth Project:: http://alioth.debian.org/projects/dbnpolicy (exists
44 to manage the repository but not otherwise used)
46 ** Interacting with the team
48 + Email contact:: mailto:debian-policy@lists.debian.org
49 + Request tracker:: http://bugs.debian.org/src:debian-policy
51 Debian Policy uses a formal procedure and a set of user tags to manage
52 the lifecycle of change proposals. For definitions of those tags and
53 proposal states and information about what the next step is for each
54 phase, see [[./Process.org][Policy changes process]].
56 Once the wording for a change has been finalized, please send a patch
57 against the current Git master branch to the bug report, if you're not
58 familiar with Git, the following commands are the basic process:
61 git clone git://anonscm.debian.org/dbnpolicy/policy.git
62 git checkout -b <local-branch-name>
64 # edit files, but don't make changes to upgrading-checklist or debian/changelog
69 # update your branch against the current master
74 git merge --no-commit <local-branch-name>
75 git reset --hard HEAD;
76 git checkout <local-branch-name>;
78 # If there are changes in master that make the branch not apply cleanly, there
79 # should have been en error during the merge step above. If there was an
80 # error, merge the master branch into the local branch, fix the conflicts, and
81 # commit the new version of the local branch.
83 # Edit files to remove conflict
86 # Checkout the local branch, to create the patch to send to the policy
87 git checkout <local-branch-name>
89 git format-patch -o $dir -s master
90 # check out the patches created in $dir
91 git send-email --from "you <your@email>" \
92 --to debian-policy@lists.debian.org \
96 <local-branch-name> is some convenient name designating your local
97 changes. You may want to use some common prefix like local-. You can
98 use git format-patch and git send-email if you want, but usually it's
103 The Debian Policy team are official project delegates (see the DPL
104 delegation). All of the Policy team members do basically the same
105 work: shepherd proposals, propose wording, and merge changes when
106 consensus has been reached. The current delegates are:
108 + Andreas Barth (aba)
109 + Bill Allombert (ballombe)
110 + Charles Plessy (plessy)
111 + Jonathan Nieder (jrnieder)
116 The Debian Policy team is responsible for maintaining and coordinating
117 updates to the Debian Policy Manual and all the other policy documents
118 released as part of the "debian-policy" package.
120 The Debian Policy Editors:
122 + Guide the work on the Debian Policy Manual and related documents as a
123 collaborative process where developers review and second or object to
124 proposals, usually on the debian-policy mailing list.
126 + Count seconds and weight objections to proposals, to determine whether
127 they have reached sufficient consensus to be included, and accept
128 consensual proposals.
130 + Reject or refer to the Technical Committee proposals that fail to
133 + Commit changes to the version control system repository used to
134 maintain the Debian Policy Manual and related documents.
136 + Maintain the "debian-policy" package. As package maintainers, they
137 have the last word on package content, releases, bug reports, etc.
139 Everything else can be done by anyone, or any DD (depending on the
140 outcome of the discussion about seconding). We explicitly want any
141 Debian DD to review and second or object to proposals. The more
142 participation, the better. Many other people are active on the Policy
143 mailing list without being project delegates.
145 In addition to the main technical manual, the team currently also maintains:
147 + [[http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/][Machine-readable debian/copyright format]]
148 + [[http://www.debian.org/doc/packaging-manuals/menu-policy/][Debian Menu sub-policy]]
149 + [[http://www.debian.org/doc/packaging-manuals/perl-policy/][Debian Perl Policy]]
150 + [[http://www.debian.org/doc/packaging-manuals/debconf_specification.html][Debconf Specification]]
151 + [[http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt][Authoritative list of virtual package names ]]
153 These documents are maintained using the [[./Process.org][Policy changes process]], and
154 the current state of all change proposals is tracked using the
155 [[http://bugs.debian.org/src:debian-policy][debian-policy BTS]].
159 The best way to help is to review the [[http://bugs.debian.org/src:debian-policy][current open bugs]], pick a bug
160 that no one is currently shepherding (ask on
161 [[mailto:debian-policy@lists.debian.org][debian-policy@lists.debian.org]] if you're not sure if a particular bug
162 is being shepherded), and help it through the change process. This
163 will involve guiding the discussion, seeking additional input
164 (particularly from experts in the area being discussed), possibly
165 raising the issue on other mailing lists, proposing or getting other
166 people to propose specific wording changes, and writing diffs against
167 the current Policy document. All of the steps of [[./Process.org][Policy changes process]]
168 can be done by people other than Policy team members except
169 the final acceptance steps and almost every change can be worked on
170 independently, so there's a lot of opportunity for people to help.
172 There are also some other, larger projects:
174 + Policy is currently maintained in DebianDoc-SGML, which is no longer
175 very actively maintained and isn't a widely used or understood
176 format. The most logical replacement would be DocBook. However,
177 DocBook is a huge language with many tags and options, making it
178 rather overwhelming. We badly need someone with DocBook experience
179 to write a style guide specifying exactly which tags should be used
180 and what they should be used for so that we can limit ourselves to
181 an easy-to-understand and documented subset of the language.
182 + Policy contains several appendices which are really documentation of
183 how parts of the dpkg system works rather than technical
184 Policy. Those appendices should be removed from the Policy document
185 and maintained elsewhere, probably as part of dpkg, and any Policy
186 statements in them moved into the main document. This project will
187 require reviewing the current contents of the appendices and feeding
188 the useful bits that aren't currently documented back to the dpkg
189 team as documentation patches.
190 + Policy has grown organically over the years and suffers from
191 organizational issues because of it. It also doesn't make use of the
192 abilities that a current XML language might give us, such as being
193 able to extract useful portions of the document (all *must*
194 directives, for example). There has been quite a bit of discussion
195 of a new format that would allow for this, probably as part of
196 switching to DocBook, but as yet such a reorganization and reworking
197 has not been started.
199 If you want to work on any of these projects, please mail
200 [[mailto:debian-policy@lists.debian.org][debian-policy@lists.debian.org ]] for more information. We'll be happy to
201 help you get started.
203 ** Maintenance procedures
207 The Git repository used for Debian Policy has the following branches:
209 + master:: the current accepted changes that will be in the next release
210 + bug<number>-<user>:: changes addressing bug <number>, shepherded by <user>
211 + rra:: old history of Russ's arch repository, now frozen
212 + srivasta:: old history of Manoj's arch repository
216 The process used by Policy team members to manage a bug, once there is
217 proposed wording, is:
219 + Create a bug<number>-<user> branch for the bug, where <number> is
220 the bug number in the BTS and <user> is a designator of the Policy
221 team member who is shepherding the bug.
222 + Commit wording changes in that branch until consensus is
223 achieved. Do not modify debian/changelog or upgrading-checklist.html
224 during this phase. Use the BTS to track who proposed the wording and
226 + git pull master to make sure you have the latest version.
227 + Once the change has been approved by enough people, git merge the
228 branch into master immediately after making the final commit adding
229 the changelog entry to minimize conflicts.
230 + add the debian/changelog and upgrading-checklist.html changes, and
232 + Push master out so other people may merge in their own bug branches
234 + Tag the bug as pending and remove other process tags.
235 + Delete the now-merged branch.
237 The Git commands used for this workflow are:
239 git checkout -b bug12345-rra master
243 git push origin bug12345-rra
245 # update your local master branch
250 git merge --no-commit bug12345-rra
251 git reset --hard HEAD;
253 # If there are changes in master that make the branch not apply cleanly, there
254 # should have been en error during the merge step above. If there was an
255 # error, merge the master branch into the local branch, fix the conflicts, and
256 # commit the new version of the local branch.
257 : git checkout bug12345-rra
259 # Edit files to remove conflict
263 git merge bug12345-rra
264 # edit debian/changelog and upgrading-checklist.html
265 git add debian/changelog upgrading-checklist.html
267 git push origin master
268 git branch -d bug12345-rra
269 git push origin :bug12345-rra
272 For the debian/changelog entry, use the following format:
274 * <document>: <brief change description>
275 Wording: <author of wording>
278 Closes: <bug numbers>
283 * Policy: better document version ranking and empty Debian revisions
284 Wording: Russ Allbery <rra@debian.org>
285 Seconded: Raphaƫl Hertzog <hertzog@debian.org>
286 Seconded: Manoj Srivastava <srivasta@debian.org>
287 Seconded: Guillem Jover <guillem@debian.org>
288 Closes: #186700, #458910
293 After commits to master have been pushed, either by you or by another
294 Policy team member, you will generally want to update your working bug
295 branches. The equivalent of the following commands should do that:
298 for i in `git show-ref --heads | awk '{print $2}'`; do
300 if [ "$j" != "master" ]; then
301 git checkout $j && git merge master
304 git push --all origin
307 assuming that you haven't packed the refs in your repository.
311 For a final Policy release, change UNRELEASED to unstable in
312 debian/changelog and update the timestamp to match the final release
313 time (dch -r may be helpful for this), update the release date in
314 upgrading-checklist.html, update Standards-Version in debian/control,
315 and commit that change. Then do the final release build and make sure
316 that it builds and installs.
318 Then, tag the repository and push the final changes to Alioth:
323 git push --tags origin
326 replacing the version number with the version of the release, of course.
328 Finally, announce the new Policy release on debian-devel-announce,
329 including in the announcement the upgrading-checklist section for the
332 ** Setting release goals
334 Policy has a large bug backlog, and each bug against Policy tends to
335 take considerable time and discussion to resolve. I've found it
336 useful, when trying to find a place to start, to pick a manageable set
337 of bugs and set as a target resolving them completely before the next
338 Policy release. Resolving a bug means one of the following:
340 + Proposing new language to address the bug that's seconded and approved by
341 the readers of the Policy list following the [[./Progress.org][Policy changes process]] (or
342 that's accepted by one of the Policy delegates if the change isn't
343 normative; i.e., doesn't change the technical meaning of the document).
344 + Determining that the bug is not relevant to Policy and closing it.
345 + Determining that either there is no consensus that the bug indicates
346 a problem, that the solutions that we can currently come up with are
347 good solutions, or that Debian is ready for the change. These bugs
348 are tagged wontfix and then closed after a while. A lot of Policy
349 bugs fall into this category; just because it would be useful to
350 have a policy in some area doesn't mean that we're ready to make
351 one, and keeping the bugs open against Policy makes it difficult to
352 tell what requires work. If the problem is worth writing a policy
353 for, it will come up again later when hopefully the project
354 consensus is more mature.
356 Anyone can pick bugs and work resolve them. The final determination to
357 accept a wording change or reject a bug will be made by a Policy
358 delegate, but if a patch is already written and seconded, or if a
359 summary of why a bug is not ready to be acted on is already written,
360 the work is much easier for the Policy delegate.
362 One of the best ways to help out is to pick one or two bugs (checking
363 on the Policy list first), say that you'll make resolving them a goal
364 for the next release, and guide the discussion until the bugs can
365 reach one of the resolution states above.