Debian Policy uses a formal procedure and a set of user tags to manage the life cycle of change proposals. For definitions of those tags and proposal states and information about what the next step is for each phase, see Policy changes process.
Given that most changes need to be discussed according to this process, we have merge requests on salsa turned off. Please submit a bug to the BTS, either with patches attached, or a reference to a git branch that is publically fetchable.
Once the wording for a change has been finalized, please send a patch against the current Git master branch to the bug report, if you're not familiar with Git, the following commands are the basic process:
git clone git://anonscm.debian.org/dbnpolicy/policy.git
git checkout -b <local-branch-name>
# edit files, but don't make changes to upgrading-checklist or debian/changelog
git add <files>
git commit
# repeat as necessary
# update your branch against the current master
git checkout master
git pull
git checkout master
git merge --no-commit <local-branch-name>
git reset --hard HEAD;
git checkout <local-branch-name>;
# If there are changes in master that make the branch not apply cleanly,
# there should have been en error during the merge step above. If there
# was an error, merge the master branch into the local branch, fix the
# conflicts, and commit the new version of the local branch.
: git merge master
# Edit files to remove conflict
: git commit -s
# Checkout the local branch, to create the patch to send to the policy
git checkout <local-branch-name>
dir=$(mktemp -d)
git format-patch -o $dir -s master
# check out the patches created in $dir
git send-email --from "you <your@email>" \
--to debian-policy@lists.debian.org \
$dir/
<local-branch-name> is some convenient name designating your local changes. You may want to use some common prefix like local-. You can use git format-patch and git send-email if you want, but usually it's overkill.
The Debian Policy team are official project delegates (see the DPL delegation). All of the Policy team members do basically the same work: shepherd proposals, propose wording, and merge changes when consensus has been reached. The current delegates are:
The Debian Policy team is responsible for maintaining and coordinating updates to the Debian Policy Manual and all the other policy documents released as part of the "debian-policy" package.
The Debian Policy Editors:
Everything else can be done by anyone, or any DD (depending on the outcome of the discussion about seconding). We explicitly want any Debian DD to review and second or object to proposals. The more participation, the better. Many other people are active on the Policy mailing list without being project delegates.
In addition to the main technical manual, the team currently also maintains:
These documents are maintained using the Policy changes process (see final appendix to policy), and the current state of all change proposals is tracked using the debian-policy BTS.
The best way to help is to review the current open bugs, pick a bug that no one is currently shepherding (ask on debian-policy@lists.debian.org if you're not sure if a particular bug is being shepherded), and help it through the change process. This will involve guiding the discussion, seeking additional input (particularly from experts in the area being discussed), possibly raising the issue on other mailing lists, proposing or getting other people to propose specific wording changes, and writing diffs against the current Policy document. All of the steps of the Policy changes process can be done by people other than Policy team members except the final acceptance steps and almost every change can be worked on independently, so there's a lot of opportunity for people to help.
There are also some other, larger projects:
If you want to work on any of these projects, please mail debian-policy@lists.debian.org for more information. We'll be happy to help you get started.
We have recently begun accepting translations for the Policy Manual. Please follow the procedures of the localisation team for the language into which you wish to translate.
When you have a translation for us to merge, push a branch to a git server somewhere, and open a bug requesting that we merge your translation. We plan to enable merge requests for the purpose of accepting translations at some point.
The Git repository used for Debian Policy has the following branches:
The process used by Policy team members to manage a bug, once there is proposed wording, is:
The Git commands used for this workflow are:
git checkout -b bug12345-rra master
# edit files
# git add files
git commit
git push origin bug12345-rra
# iterate until good
# update your local master branch
git checkout master
git pull
git checkout master
git merge --no-commit bug12345-rra
git reset --hard HEAD;
# If there are changes in master that make the branch not apply cleanly,
# there should have been en error during the merge step above. If there
# was an error, merge the master branch into the local branch, fix the
# conflicts, and commit the new version of the local branch.
: git checkout bug12345-rra
: git merge master
# Edit files to remove conflict
: git commit -s
git checkout master
git merge bug12345-rra
# edit debian/changelog and upgrading-checklist.xml
git add debian/changelog upgrading-checklist.xml
git commit
git push origin master
git branch -d bug12345-rra
git push origin :bug12345-rra
For the debian/changelog entry, use the following format:
* <document>: <brief change description>
Wording: <author of wording>
Seconded: <seconder>
Seconded: <seconder>
Closes: <bug numbers>
For example:
* Policy: better document version ranking and empty Debian revisions
Wording: Russ Allbery <rra@debian.org>
Seconded: Raphaël Hertzog <hertzog@debian.org>
Seconded: Manoj Srivastava <srivasta@debian.org>
Seconded: Guillem Jover <guillem@debian.org>
Closes: #186700, #458910
After commits to master have been pushed, either by you or by another Policy team member, you will generally want to update your working bug branches. The equivalent of the following commands should do that:
for i in `git show-ref --heads | awk '{print $2}'`; do
j=$(basename $i)
if [ "$j" != "master" ]; then
git checkout $j && git merge master
fi
done
git push --all origin
assuming that you haven't packed the refs in your repository.
For a final Policy release,
dch -r to finalise changelogCommit these changes:
git commit debian/changelog debian/control policy/upgrading-checklist.rst -m"finalise 3.9.8.0"
Make sure the package builds and installs: dgit sbuild or
equivalent
Tag and upload: either
git tag -s 3.9.8.0 followed by dput; ordgit pushPush to salsa:
git push --tags origin
Announce on debian-devel-announce, including upgrading checklist section for new release
Policy has a large bug backlog, and each bug against Policy tends to take considerable time and discussion to resolve. I've found it useful, when trying to find a place to start, to pick a manageable set of bugs and set as a target resolving them completely before the next Policy release. Resolving a bug means one of the following:
Anyone can pick bugs and work resolve them. The final determination to accept a wording change or reject a bug will be made by a Policy delegate, but if a patch is already written and seconded, or if a summary of why a bug is not ready to be acted on is already written, the work is much easier for the Policy delegate.
One of the best ways to help out is to pick one or two bugs (checking on the Policy list first), say that you'll make resolving them a goal for the next release, and guide the discussion until the bugs can reach one of the resolution states above.
Debian Policy 4.2.0.1, 2018-08-03