From: Russ Allbery Date: Mon, 31 May 2010 16:34:44 +0000 (-0700) Subject: Merge branch 'master' into bug530687-rra X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=baea58c43486488c3c9bd0b4e52957ce88ddd94c;hp=ec4fbc8a14591d5f199003971cfdb698c6c5c93f;p=debian%2Fdebian-policy.git Merge branch 'master' into bug530687-rra --- diff --git a/.gitignore b/.gitignore index ab942fa..22a2f0c 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ /policy.html/ /stamp-build /version.ent +*-1.html *.html.tar.gz *.pdf *.pdf.gz diff --git a/Makefile b/Makefile index 1d0852e..20433d7 100644 --- a/Makefile +++ b/Makefile @@ -4,6 +4,17 @@ policy.sgml: version.ent menu-policy.sgml: version.ent mime-policy.sgml: version.ent +ifneq (,$(strip $(HAVE_ORG_EMACS))) +%.txt: %.org + $(EMACS) --batch -Q -l ./README-css.el -l org -l org-ascii --visit $^ \ + --funcall org-export-as-ascii >/dev/null 2>&1 + test "$@" != "README.txt" || \ + perl -pli -e 's,./Process.org,Process.txt,g' $@ +%.html: %.org + $(EMACS) --batch -Q -l ./README-css.el -l org --visit $^ \ + --funcall org-export-as-html-batch >/dev/null 2>&1 +endif + %.validate: % nsgmls -wall -gues $< @@ -45,8 +56,7 @@ pdf: policy.pdf policy: html txt ps pdf leavealone := $(FHS_HTML) $(FHS_FILES) $(FHS_ARCHIVE) \ - libc6-migration.txt \ - upgrading-checklist.html virtual-package-names-list.txt + libc6-migration.txt .PHONY: distclean distclean: diff --git a/Process.html b/Process.html new file mode 100644 index 0000000..9440ae7 --- /dev/null +++ b/Process.html @@ -0,0 +1,423 @@ + + + + +
+ UP + | + HOME +
+ +Debian Policy changes process + + + + + + + + + + + + + + +
+

Debian Policy changes process

+ + +
+

Change Goals

+
+ + +
    +
  • +The change should be technically correct, and consistent with the +rest of the policy document. This means no legislating the value of +π. This also means that the proposed solution be known to work; +iterative design processes do not belong in policy. +
  • +
  • +The change should not be too disruptive; if very many packages +become instantly buggy, then instead there should be a transition +plan. Exceptions should be rare (only if the current state is really +untenable), and probably blessed by the TC. +
  • +
  • +The change has to be reviewed in depth, in the open, where any one +may contribute; a publicly accessible, archived, open mailing list. +
  • +
  • +Proposal should be addressed in a timely fashion. +
  • +
  • +Any domain experts should be consulted, since not every policy +mailing list subscriber is an expert on everything, including policy +maintainers. +
  • +
  • +The goal is rough consensus on the change, which should not be hard +if the matter is technical. Technical issues where there is no +agreement should be referred to the TC; non-technical issues should +be referred to the whole developer body, and perhaps general +resolutions lie down that path. +
  • +
  • +Package maintainers whose packages may be impacted should have +access to policy change proposals, even if they do not subscribe to +policy mailing lists (policy gazette?). + +
  • +
+
+ +
+ +
+

Current Process

+
+ + +

+Each suggested change goes through different states. These states are +denoted through either usertags of the +debian-policy@packages.debian.org user or, for patch, pending, and +wontfix, regular tags. +

+

+Current list of bugs +

+

+The Policy delegates are responsible for managing the tags on bugs and +will update tags as new bugs are submitted or as activity happens on +bugs. All Debian Developers should feel free to add the seconded tag +as described below. Other tags should be changed with the coordination +of the Policy Team. +

+ +
+ +
+

State A: Issue raised

+
+ + +

+Detect need, like gaps/flaws in current policy, or a new rule should +be added. Any user or developer may start this step. There is a +decision point here, not all issues are in scope of policy. +TAG: issue +

+

+What needs to happen next: If this is in scope for Policy, discuss the +issue and possible solutions, moving to the discussion tag, or if the +matter is sufficiently clear, go directly to a proposal for how to +address it, moving to the proposal tag. If this is not in scope for +Policy, close the bug. +

+
+ +
+ +
+

State B: Discussion

+
+ + +

+Discuss remedy. Alternate proposals. Discussion guided by +delegates. There should be a clear time limit to this stage, but as +yet we have not set one. +TAG: discussion +

+

+What needs to happen next: Reach a conclusion and consensus in the +discussion and make a final proposal for what should be changed (if +anything), moving to the proposal tag. +

+
+ +
+ +
+

State D: Proposal

+
+ + +

+A final proposal has emerged from the discussion, and there is a rough +consensus on how to proceed to resolve the issue. +TAG: proposal +

+

+What needs to happen next: Provided that the rough consensus persists, +develop a patch against the current Policy document with specific +wording of the change. Often this is done in conjunction with the +proposal, in which case one may skip this step and move directly to +patch tag. +

+
+ +
+ +
+

State E: Wording proposed

+
+ + +

+A patch against the Policy document reflecting the consensus has been +created and is waiting for formal seconds. The standard patch tag is +used for this state, since it's essentially equivalent to the standard +meaning of that tag. +TAG: patch +

+

+What needs to happen next: The proposal needs to be reviewed and +seconded. Any Debian developer who agrees with the change and the +conclusion of rough consensus from the discussion should say so in the +bug log by seconding the proposal. +

+
+ +
+ +
+

State F: Seconded

+
+ + +

+The proposal is signed off on by N Debian Developers. To start with, +we're going with N=3, meaning that if three Debian Developers agree, +not just with the proposal but with the conclusion that it reflects +consensus and addresses the original issue – it is considered +eligible for inclusion in the next version of Policy. Since Policy is +partly a technical project governance method, one must be a Debian +Developer to formally second, although review and discussion is +welcome from anyone. Once this tag has been applied, the bug is +waiting for a Policy team member to apply the patch to the package +repository. +TAG: seconded +

+

+What needs to happen next: A Policy maintainer does the final review +and confirmation, and then applies the patch for the next Policy +release. +

+

+This tag is not used very much because normally a Policy maintainer +applies the patch and moves the proposal to the next state once enough +seconds are reached. +

+
+ +
+ +
+

State G: Accepted

+
+ + +

+Change accepted, will be in next upload. The standard pending tag is +used for this state since it matches the regular meaning of +pending. +TAG: pending +

+

+What needs to happen next: The bug is now in the waiting queue for the +next Policy release, and there's nothing left to do except for upload +a new version of Policy. +

+
+ +
+ +
+

State H: Reject

+
+ + +

+Rejected proposals. The standard wontfix is used for this +state. Normally, bugs in this state will not remain open; instead, a +Policy team member will close them with an explanation. The submitter +may then appeal to the tech-ctte if they so desire. Alternately, +issues appealed to the tech-ctte may remain open with this tag while +that appeal proceeds. +TAG: wontfix +

+

+We may use one of the following tags here, but to date we have only +used dubious and ctte. It's not clear whether we need more tags for +this tage. +

+
+
dubious
+Not a policy matter +
+
ctte
+Referred to the Technical Committee (tech-ctte) +
+
devel
+Referred to the developer body +
+
delegate
+Rejected by a Policy delegate +
+
obsolete
+The proposal timed out without a conclusion + +
+
+ +

What needs to happen next: The bug should be closed once a final +resolution is reached, or retagged to an appropriate state if that +final resolution reverses the decision to reject the proposal. +

+
+
+ +
+ +
+

Other Tags

+
+ + +

+All Policy bugs are additionally categorized by class of bug. +

+

+The normative tag is used for bugs that make normative changes to +Policy, meaning that the dictates of Policy will change in some +fashion as part of the resolution of the bug if the proposal is +accepted. The full process is followed for such bugs. +TAG: normative +

+

+The informative tag is used for bugs about wording issues, typos, +informative footnotes, or other changes that do not affect the formal +dictates of Policy, just the presentation. The same tags are used for +these bugs for convenience, but the Policy maintainers may make +informative changes without following the full process. Informative +bugs fall under their discretion. +TAG: informative +

+

+The packaging tag is used for bugs about the packaging and build +process of the debian-policy Debian package. These bugs do not follow +the normal process and will not have the other tags except for pending +and wontfix (used with their normal meanings). +TAG: packaging +

+
+
+

Author: Margarita Manterola, Clint Adams, Russ Allbery, and Manoj Srivastava +<srivasta@debian.org> +

+

Date: 2009-09-13 16:13:52 CDT

+

HTML generated by org-mode 6.30trans in emacs 23

+
+
+ + diff --git a/Process.org b/Process.org new file mode 100644 index 0000000..7cb0544 --- /dev/null +++ b/Process.org @@ -0,0 +1,205 @@ +-*- mode: org; fill-column: 78 -*- +#+STARTUP: showall +#+STARTUP: lognotedone lognotestate +#+OPTIONS: H:4 toc:2 +#+TITLE: Debian Policy changes process +#+AUTHOR: Margarita Manterola, Clint Adams, Russ Allbery, and Manoj Srivastava +#+EMAIL: srivasta@debian.org +#+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 +#+LINK_HOME: http://wiki.debian.org/Teams/Policy +#+LINK_UP: http://www.debian.org/ + +\usepackage{landscape} + +\setlength{\oddsidemargin}{0in} % default=0in +\setlength{\textwidth}{9in} % default=9in + +\setlength{\columnsep}{0.5in} % default=10pt +\setlength{\columnseprule}{1pt} % default=0pt (no line) + +\setlength{\textheight}{5.85in} % default=5.15in +\setlength{\topmargin}{-0.15in} % default=0.20in +\setlength{\headsep}{0.25in} % default=0.35in + +\setlength{\parskip}{1.2ex} +\setlength{\parindent}{0mm} +\pagestyle{empty} + +\setlength{\headheight}{0pt} +\setlength{\headsep}{0pt} +\setlength{\footskip}{5pt} +\setlength{\textheight}{9.0in} +\setlength{\textwidth}{6.5in} + +To introduce a change in the current DebianPolicy, the change proposal +has to go through a certain process. + +* Change Goals + ++ The change should be technically correct, and consistent with the + rest of the policy document. This means no legislating the value of + π. This also means that the proposed solution be known to work; + iterative design processes do not belong in policy. ++ The change should not be too disruptive; if very many packages + become instantly buggy, then instead there should be a transition + plan. Exceptions should be rare (only if the current state is really + untenable), and probably blessed by the TC. ++ The change has to be reviewed in depth, in the open, where any one + may contribute; a publicly accessible, archived, open mailing list. ++ Proposal should be addressed in a timely fashion. ++ Any domain experts should be consulted, since not every policy + mailing list subscriber is an expert on everything, including policy + maintainers. ++ The goal is rough consensus on the change, which should not be hard + if the matter is technical. Technical issues where there is no + agreement should be referred to the TC; non-technical issues should + be referred to the whole developer body, and perhaps general + resolutions lie down that path. ++ Package maintainers whose packages may be impacted should have + access to policy change proposals, even if they do not subscribe to + policy mailing lists (policy gazette?). + +* Current Process + +Each suggested change goes through different states. These states are +denoted through either usertags of the +[[mailto:debian-policy@packages.debian.org][debian-policy@packages.debian.org]] user or, for patch, pending, and +wontfix, regular tags. + +[[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done][Current list of bugs]] + +The Policy delegates are responsible for managing the tags on bugs and +will update tags as new bugs are submitted or as activity happens on +bugs. All Debian Developers should feel free to add the seconded tag +as described below. Other tags should be changed with the coordination +of the Policy Team. + +** State A: Issue raised + +Detect need, like gaps/flaws in current policy, or a new rule should +be added. Any user or developer may start this step. There is a +decision point here, not all issues are in scope of policy. +[[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&tag=issue][TAG: issue]] + +What needs to happen next: If this is in scope for Policy, discuss the +issue and possible solutions, moving to the discussion tag, or if the +matter is sufficiently clear, go directly to a proposal for how to +address it, moving to the proposal tag. If this is not in scope for +Policy, close the bug. + +** State B: Discussion + +Discuss remedy. Alternate proposals. Discussion guided by +delegates. There should be a clear time limit to this stage, but as +yet we have not set one. +[[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=discussion][TAG: discussion]] + +What needs to happen next: Reach a conclusion and consensus in the +discussion and make a final proposal for what should be changed (if +anything), moving to the proposal tag. + +** State D: Proposal + +A final proposal has emerged from the discussion, and there is a rough +consensus on how to proceed to resolve the issue. +[[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=proposal][TAG: proposal]] + +What needs to happen next: Provided that the rough consensus persists, +develop a patch against the current Policy document with specific +wording of the change. Often this is done in conjunction with the +proposal, in which case one may skip this step and move directly to +patch tag. + +** State E: Wording proposed + +A patch against the Policy document reflecting the consensus has been +created and is waiting for formal seconds. The standard patch tag is +used for this state, since it's essentially equivalent to the standard +meaning of that tag. +[[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=patch][TAG: patch]] + +What needs to happen next: The proposal needs to be reviewed and +seconded. Any Debian developer who agrees with the change and the +conclusion of rough consensus from the discussion should say so in the +bug log by seconding the proposal. + +** State F: Seconded + +The proposal is signed off on by N Debian Developers. To start with, +we're going with N=3, meaning that if three Debian Developers agree, +not just with the proposal but with the conclusion that it reflects +consensus and addresses the original issue -- it is considered +eligible for inclusion in the next version of Policy. Since Policy is +partly a technical project governance method, one must be a Debian +Developer to formally second, although review and discussion is +welcome from anyone. Once this tag has been applied, the bug is +waiting for a Policy team member to apply the patch to the package +repository. +[[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=seconded][TAG: seconded]] + +What needs to happen next: A Policy maintainer does the final review +and confirmation, and then applies the patch for the next Policy +release. + +This tag is not used very much because normally a Policy maintainer +applies the patch and moves the proposal to the next state once enough +seconds are reached. + +** State G: Accepted + +Change accepted, will be in next upload. The standard pending tag is +used for this state since it matches the regular meaning of +pending. +[[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=pending][TAG: pending]] + +What needs to happen next: The bug is now in the waiting queue for the +next Policy release, and there's nothing left to do except for upload +a new version of Policy. + +** State H: Reject + +Rejected proposals. The standard wontfix is used for this +state. Normally, bugs in this state will not remain open; instead, a +Policy team member will close them with an explanation. The submitter +may then appeal to the tech-ctte if they so desire. Alternately, +issues appealed to the tech-ctte may remain open with this tag while +that appeal proceeds. +[[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=rejected][TAG: wontfix]] + +We may use one of the following tags here, but to date we have only +used dubious and ctte. It's not clear whether we need more tags for +this tage. + ++ *dubious* :: Not a policy matter ++ *ctte* :: Referred to the Technical Committee (tech-ctte) ++ *devel* :: Referred to the developer body ++ *delegate* :: Rejected by a Policy delegate ++ *obsolete* :: The proposal timed out without a conclusion + +What needs to happen next: The bug should be closed once a final +resolution is reached, or retagged to an appropriate state if that +final resolution reverses the decision to reject the proposal. + +* Other Tags + +All Policy bugs are additionally categorized by class of bug. + +The normative tag is used for bugs that make normative changes to +Policy, meaning that the dictates of Policy will change in some +fashion as part of the resolution of the bug if the proposal is +accepted. The full process is followed for such bugs. +[[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=normative][TAG: normative]] + +The informative tag is used for bugs about wording issues, typos, +informative footnotes, or other changes that do not affect the formal +dictates of Policy, just the presentation. The same tags are used for +these bugs for convenience, but the Policy maintainers may make +informative changes without following the full process. Informative +bugs fall under their discretion. +[[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=informative][TAG: informative]] + +The packaging tag is used for bugs about the packaging and build +process of the debian-policy Debian package. These bugs do not follow +the normal process and will not have the other tags except for pending +and wontfix (used with their normal meanings). +[[http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=packaging][TAG: packaging]] diff --git a/Process.txt b/Process.txt new file mode 100644 index 0000000..f130c1d --- /dev/null +++ b/Process.txt @@ -0,0 +1,216 @@ + Debian Policy changes process + ============================= + +Author: Margarita Manterola, Clint Adams, Russ Allbery, and Manoj Srivastava +Date: 2009-09-13 01:17:13 CDT + + +Change Goals +~~~~~~~~~~~~~ + ++ The change should be technically correct, and consistent with the + rest of the policy document. This means no legislating the value of + π. This also means that the proposed solution be known to work; + iterative design processes do not belong in policy. ++ The change should not be too disruptive; if very many packages + become instantly buggy, then instead there should be a transition + plan. Exceptions should be rare (only if the current state is really + untenable), and probably blessed by the TC. ++ The change has to be reviewed in depth, in the open, where any one + may contribute; a publicly accessible, archived, open mailing list. ++ Proposal should be addressed in a timely fashion. ++ Any domain experts should be consulted, since not every policy + mailing list subscriber is an expert on everything, including policy + maintainers. ++ The goal is rough consensus on the change, which should not be hard + if the matter is technical. Technical issues where there is no + agreement should be referred to the TC; non-technical issues should + be referred to the whole developer body, and perhaps general + resolutions lie down that path. ++ Package maintainers whose packages may be impacted should have + access to policy change proposals, even if they do not subscribe to + policy mailing lists (policy gazette?). + +Current Process +~~~~~~~~~~~~~~~~ + +Each suggested change goes through different states. These states are +denoted through either usertags of the +[debian-policy@packages.debian.org] user or, for patch, pending, and +wontfix, regular tags. + +[Current list of bugs] + +The Policy delegates are responsible for managing the tags on bugs and +will update tags as new bugs are submitted or as activity happens on +bugs. All Debian Developers should feel free to add the seconded tag +as described below. Other tags should be changed with the coordination +of the Policy Team. + + +[debian-policy@packages.debian.org]: mailto:debian-policy@packages.debian.org +[Current list of bugs]: http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done + +State A: Issue raised +====================== + +Detect need, like gaps/flaws in current policy, or a new rule should +be added. Any user or developer may start this step. There is a +decision point here, not all issues are in scope of policy. +[TAG: issue] + +What needs to happen next: If this is in scope for Policy, discuss the +issue and possible solutions, moving to the discussion tag, or if the +matter is sufficiently clear, go directly to a proposal for how to +address it, moving to the proposal tag. If this is not in scope for +Policy, close the bug. + + +[TAG: issue]: http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&tag=issue + +State B: Discussion +==================== + +Discuss remedy. Alternate proposals. Discussion guided by +delegates. There should be a clear time limit to this stage, but as +yet we have not set one. +[TAG: discussion] + +What needs to happen next: Reach a conclusion and consensus in the +discussion and make a final proposal for what should be changed (if +anything), moving to the proposal tag. + + +[TAG: discussion]: http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=discussion + +State D: Proposal +================== + +A final proposal has emerged from the discussion, and there is a rough +consensus on how to proceed to resolve the issue. +[TAG: proposal] + +What needs to happen next: Provided that the rough consensus persists, +develop a patch against the current Policy document with specific +wording of the change. Often this is done in conjunction with the +proposal, in which case one may skip this step and move directly to +patch tag. + + +[TAG: proposal]: http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=proposal + +State E: Wording proposed +========================== + +A patch against the Policy document reflecting the consensus has been +created and is waiting for formal seconds. The standard patch tag is +used for this state, since it's essentially equivalent to the standard +meaning of that tag. +[TAG: patch] + +What needs to happen next: The proposal needs to be reviewed and +seconded. Any Debian developer who agrees with the change and the +conclusion of rough consensus from the discussion should say so in the +bug log by seconding the proposal. + + +[TAG: patch]: http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=patch + +State F: Seconded +================== + +The proposal is signed off on by N Debian Developers. To start with, +we're going with N=3, meaning that if three Debian Developers agree, +not just with the proposal but with the conclusion that it reflects +consensus and addresses the original issue -- it is considered +eligible for inclusion in the next version of Policy. Since Policy is +partly a technical project governance method, one must be a Debian +Developer to formally second, although review and discussion is +welcome from anyone. Once this tag has been applied, the bug is +waiting for a Policy team member to apply the patch to the package +repository. +[TAG: seconded] + +What needs to happen next: A Policy maintainer does the final review +and confirmation, and then applies the patch for the next Policy +release. + +This tag is not used very much because normally a Policy maintainer +applies the patch and moves the proposal to the next state once enough +seconds are reached. + + +[TAG: seconded]: http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=seconded + +State G: Accepted +================== + +Change accepted, will be in next upload. The standard pending tag is +used for this state since it matches the regular meaning of +pending. +[TAG: pending] + +What needs to happen next: The bug is now in the waiting queue for the +next Policy release, and there's nothing left to do except for upload +a new version of Policy. + + +[TAG: pending]: http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=pending + +State H: Reject +================ + +Rejected proposals. The standard wontfix is used for this +state. Normally, bugs in this state will not remain open; instead, a +Policy team member will close them with an explanation. The submitter +may then appeal to the tech-ctte if they so desire. Alternately, +issues appealed to the tech-ctte may remain open with this tag while +that appeal proceeds. +[TAG: wontfix] + +We may use one of the following tags here, but to date we have only +used dubious and ctte. It's not clear whether we need more tags for +this tage. + +*dubious*: Not a policy matter +*ctte*: Referred to the Technical Committee (tech-ctte) +*devel*: Referred to the developer body +*delegate*: Rejected by a Policy delegate +*obsolete*: The proposal timed out without a conclusion + +What needs to happen next: The bug should be closed once a final +resolution is reached, or retagged to an appropriate state if that +final resolution reverses the decision to reject the proposal. + + +[TAG: wontfix]: http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=rejected + +Other Tags +~~~~~~~~~~~ + +All Policy bugs are additionally categorized by class of bug. + +The normative tag is used for bugs that make normative changes to +Policy, meaning that the dictates of Policy will change in some +fashion as part of the resolution of the bug if the proposal is +accepted. The full process is followed for such bugs. +[TAG: normative] + +The informative tag is used for bugs about wording issues, typos, +informative footnotes, or other changes that do not affect the formal +dictates of Policy, just the presentation. The same tags are used for +these bugs for convenience, but the Policy maintainers may make +informative changes without following the full process. Informative +bugs fall under their discretion. +[TAG: informative] + +The packaging tag is used for bugs about the packaging and build +process of the debian-policy Debian package. These bugs do not follow +the normal process and will not have the other tags except for pending +and wontfix (used with their normal meanings). +[TAG: packaging] + +[TAG: normative]: http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=normative +[TAG: informative]: http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=informative +[TAG: packaging]: http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=packaging + diff --git a/README-css.el b/README-css.el new file mode 100644 index 0000000..9b7cf85 --- /dev/null +++ b/README-css.el @@ -0,0 +1,81 @@ +(setq + org-export-html-style-include-default nil + org-export-html-style + " + + + +") diff --git a/README.html b/README.html new file mode 100644 index 0000000..19608a2 --- /dev/null +++ b/README.html @@ -0,0 +1,691 @@ + + + + +
+ UP + | + HOME +
+ +Debian Policy + + + + + + + + + + + + + + +
+

Debian Policy

+ + +
+

Infrastructure

+
+ + + + +
+ +
+

Interacting with the team

+
+ + + + +

Debian Policy uses a formal procedure and a set of user tags to manage +the lifecycle 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. +

+

+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://git.debian.org/git/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. +

+
+
+ +
+ +
+

Usual Roles

+
+ + +

+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: +

+
    +
  • +Russ Allbery +
  • +
  • +Bill Allombert +
  • +
  • +Andrew McMillan +
  • +
  • +Manoj Srivastava +
  • +
  • +Colin Watson (cjwatson) + +
  • +
+ +

The special tasks of Policy delegates are: +

+
    +
  • +Commit access to the Git repository and uploads of the debian-policy +package itself, which makes them responsible for debian-policy as a +package in Debian and for making final decisions about when a new +version is released and what bits go into it. +
  • +
  • +Rejecting proposals. Anyone can argue against a proposal, but only +Policy delegates can formally reject it. +
  • +
  • +Counting seconds and weighing objections to proposals to determine +whether the proposal has sufficient support to be included. + +
  • +
+ +

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. +

+
+ +
+ +
+

Task description

+
+ + +

+The Debian Policy team is responsible for maintaining and coordinating +updates to the technical Policy manuals for the project. The primary +output of the team is the Debian Policy Manual and the assorted +subpolicies, released as the debian-policy Debian package and also +published at http://www.debian.org/doc/. +

+

+In addition to the main technical manual, the team currently also maintains: +

+ + +

These documents are maintained using the Policy changes process, and +the current state of all change proposals is tracked using the +debian-policy BTS. +

+
+ +
+ +
+

Get involved

+
+ + +

+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 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: +

+
    +
  • +Policy is currently maintained in DebianDoc-SGML, which is no longer +very actively maintained and isn't a widely used or understood +format. The most logical replacement would be DocBook. However, +DocBook is a huge language with many tags and options, making it +rather overwhelming. We badly need someone with DocBook experience +to write a style guide specifying exactly which tags should be used +and what they should be used for so that we can limit ourselves to +an easy-to-understand and documented subset of the language. +
  • +
  • +Policy contains several appendices which are really documentation of +how parts of the dpkg system works rather than technical +Policy. Those appendices should be removed from the Policy document +and maintained elsewhere, probably as part of dpkg, and any Policy +statements in them moved into the main document. This project will +require reviewing the current contents of the appendices and feeding +the useful bits that aren't currently documented back to the dpkg +team as documentation patches. +
  • +
  • +Policy has grown organically over the years and suffers from +organizational issues because of it. It also doesn't make use of the +abilities that a current XML language might give us, such as being +able to extract useful portions of the document (all must +directives, for example). There has been quite a bit of discussion +of a new format that would allow for this, probably as part of +switching to DocBook, but as yet such a reorganization and reworking +has not been started. + +
  • +
+ +

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. +

+ +
+ +
+

Maintenance procedures

+
+ + +
+ +
+ +
+

Repository layout

+
+ + +

+The Git repository used for Debian Policy has the following branches: +

+
    +
  • + master:: the current accepted changes that will be in the next release +
  • +
  • + bug<number>-<user>:: changes addressing bug <number>, shepherded by <user> +
  • +
  • + rra:: old history of Russ's arch repository, now frozen +
  • +
  • + srivasta:: old history of Manoj's arch repository + +
  • +
+
+ +
+ +
+

Managing a bug

+
+ + +

+The process used by Policy team members to manage a bug, once there is +proposed wording, is: +

+
    +
  • +Create a bug<number>-<user> branch for the bug, where <number> is +the bug number in the BTS and <user> is a designator of the Policy +team member who is shepherding the bug. +
  • +
  • +Commit wording changes in that branch until consensus is +achieved. Do not modify debian/changelog or upgrading-checklist.html +during this phase. Use the BTS to track who proposed the wording and +who seconded it. +
  • +
  • +git pull master to make sure you have the latest version. +
  • +
  • +Once the change has been approved by enough people, git merge the +branch into master immediately after making the final commit adding +the changelog entry to minimize conflicts. +
  • +
  • +add the debian/changelog and upgrading-checklist.html changes, and +commit to master. +
  • +
  • +Push master out so other people may merge in their own bug branches +without conflicts. +
  • +
  • +Tag the bug as pending and remove other process tags. +
  • +
  • +Delete the now-merged branch. + +
  • +
+ +

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.html
+git add debian/changelog upgrading-checklist.html
+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
+
+ + + + +
+ +
+ +
+

Updating branches

+
+ + +

+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. +

+
+ +
+ +
+

Making a release

+
+ + +

+For a final Policy release, change UNRELEASED to unstable in +debian/changelog and update the timestamp to match the final release +time (dch -r may be helpful for this), update the release date in +upgrading-checklist.html, update Standards-Version in debian/control, +and commit that change. Then do the final release build and make sure +that it builds and installs. +

+

+Then, tag the repository and push the final changes to Alioth: +

+ + + +
git tag -s v3.8.0.0
+git push origin
+git push --tags origin
+
+ + + + +

+replacing the version number with the version of the release, of course. +

+

+Finally, announce the new Policy release on debian-devel-announce, +including in the announcement the upgrading-checklist section for the +new release. +

+
+ +
+ +
+

Setting release goals

+
+ + +

+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: +

+
    +
  • +Proposing new language to address the bug that's seconded and approved by +the readers of the Policy list following the Policy changes process (or +that's accepted by one of the Policy delegates if the change isn't +normative; i.e., doesn't change the technical meaning of the document). +
  • +
  • +Determining that the bug is not relevant to Policy and closing it. +
  • +
  • +Determining that either there is no consensus that the bug indicates +a problem, that the solutions that we can currently come up with are +good solutions, or that Debian is ready for the change. These bugs +are tagged wontfix and then closed after a while. A lot of Policy +bugs fall into this category; just because it would be useful to +have a policy in some area doesn't mean that we're ready to make +one, and keeping the bugs open against Policy makes it difficult to +tell what requires work. If the problem is worth writing a policy +for, it will come up again later when hopefully the project +consensus is more mature. + +
  • +
+ +

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. +

+
+
+
+

Author: Manoj Srivastava And Russ Allbery +<srivasta@debian.org> +

+

Date: 2009-10-05 00:20:29 CDT

+

HTML generated by org-mode 6.31trans in emacs 23

+
+
+ + diff --git a/README.org b/README.org new file mode 100644 index 0000000..4a7458c --- /dev/null +++ b/README.org @@ -0,0 +1,359 @@ +-*- mode: org; fill-column: 78 -*- +#+STARTUP: showall +#+STARTUP: lognotedone lognotestate +#+OPTIONS: H:4 toc:2 +#+TITLE: Debian Policy +#+AUTHOR: Manoj Srivastava And Russ Allbery +#+EMAIL: srivasta@debian.org +#+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 +#+LINK_HOME: http://wiki.debian.org/Teams/Policy +#+LINK_UP: http://www.debian.org/ + +\usepackage{landscape} + +\setlength{\oddsidemargin}{0in} % default=0in +\setlength{\textwidth}{9in} % default=9in + +\setlength{\columnsep}{0.5in} % default=10pt +\setlength{\columnseprule}{1pt} % default=0pt (no line) + +\setlength{\textheight}{5.85in} % default=5.15in +\setlength{\topmargin}{-0.15in} % default=0.20in +\setlength{\headsep}{0.25in} % default=0.35in + +\setlength{\parskip}{1.2ex} +\setlength{\parindent}{0mm} +\pagestyle{empty} + +\setlength{\headheight}{0pt} +\setlength{\headsep}{0pt} +\setlength{\footskip}{5pt} +\setlength{\textheight}{9.0in} +\setlength{\textwidth}{6.5in} + + +* Infrastructure + ++ Website:: http://www.debian.org/doc/devel-manuals#policy ++ Mailing list:: debian-policy@lists.debian.org lists ++ Source Code:: + * git clone git://git.debian.org/git/dbnpolicy/policy.git + * Browser: http://git.debian.org/?p=dbnpolicy/policy.git ++ Unix group:: dbnpolicy ++ Alioth Project:: http://alioth.debian.org/projects/dbnpolicy (exists + to manage the repository but not otherwise used) + +** Interacting with the team + ++ Email contact:: mailto:debian-policy@lists.debian.org ++ Request tracker:: http://bugs.debian.org/src:debian-policy + +Debian Policy uses a formal procedure and a set of user tags to manage +the lifecycle of change proposals. For definitions of those tags and +proposal states and information about what the next step is for each +phase, see [[./Process.org][Policy changes process]]. + +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: + +#+BEGIN_SRC Sh +git clone git://git.debian.org/git/dbnpolicy/policy.git +git checkout -b + +# edit files, but don't make changes to upgrading-checklist or debian/changelog +git add +git commit +# repeat as necessary + +# update your branch against the current master +git checkout master +git pull + +git checkout master +git merge --no-commit +git reset --hard HEAD; +git checkout ; + +# 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 +dir=$(mktemp -d) +git format-patch -o $dir -s master +# check out the patches created in $dir +git send-email --from "you " \ + --to debian-policy@lists.debian.org \ + $dir/ +#+END_SRC + + 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. + +* Usual Roles + +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: + ++ Russ Allbery ++ Bill Allombert ++ Andrew McMillan ++ Manoj Srivastava ++ Colin Watson (cjwatson) + +The special tasks of Policy delegates are: + ++ Commit access to the Git repository and uploads of the debian-policy + package itself, which makes them responsible for debian-policy as a + package in Debian and for making final decisions about when a new + version is released and what bits go into it. ++ Rejecting proposals. Anyone can argue against a proposal, but only + Policy delegates can formally reject it. ++ Counting seconds and weighing objections to proposals to determine + whether the proposal has sufficient support to be included. + +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. + +* Task description + +The Debian Policy team is responsible for maintaining and coordinating +updates to the technical Policy manuals for the project. The primary +output of the team is the Debian Policy Manual and the assorted +subpolicies, released as the debian-policy Debian package and also +published at [[http://www.debian.org/doc/]]. + +In addition to the main technical manual, the team currently also maintains: + ++ [[http://www.debian.org/doc/packaging-manuals/menu-policy/][Debian Menu sub-policy]] ++ [[http://www.debian.org/doc/packaging-manuals/perl-policy/][Debian Perl Policy]] ++ [[http://www.debian.org/doc/packaging-manuals/mime-policy/][Debian MIME support sub-policy]] ++ [[http://www.debian.org/doc/packaging-manuals/debconf_specification.html][Debconf Specification]] ++ [[http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt][Authoritative list of virtual package names ]] + +These documents are maintained using the [[./Process.org][Policy changes process]], and +the current state of all change proposals is tracked using the +[[http://bugs.debian.org/src:debian-policy][debian-policy BTS]]. + +* Get involved + +The best way to help is to review the [[http://bugs.debian.org/src:debian-policy][current open bugs]], pick a bug +that no one is currently shepherding (ask on +[[mailto:debian-policy@lists.debian.org][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 [[./Process.org][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: + ++ Policy is currently maintained in DebianDoc-SGML, which is no longer + very actively maintained and isn't a widely used or understood + format. The most logical replacement would be DocBook. However, + DocBook is a huge language with many tags and options, making it + rather overwhelming. We badly need someone with DocBook experience + to write a style guide specifying exactly which tags should be used + and what they should be used for so that we can limit ourselves to + an easy-to-understand and documented subset of the language. ++ Policy contains several appendices which are really documentation of + how parts of the dpkg system works rather than technical + Policy. Those appendices should be removed from the Policy document + and maintained elsewhere, probably as part of dpkg, and any Policy + statements in them moved into the main document. This project will + require reviewing the current contents of the appendices and feeding + the useful bits that aren't currently documented back to the dpkg + team as documentation patches. ++ Policy has grown organically over the years and suffers from + organizational issues because of it. It also doesn't make use of the + abilities that a current XML language might give us, such as being + able to extract useful portions of the document (all *must* + directives, for example). There has been quite a bit of discussion + of a new format that would allow for this, probably as part of + switching to DocBook, but as yet such a reorganization and reworking + has not been started. + +If you want to work on any of these projects, please mail +[[mailto:debian-policy@lists.debian.org][debian-policy@lists.debian.org ]] for more information. We'll be happy to +help you get started. + +** Maintenance procedures + +** Repository layout + +The Git repository used for Debian Policy has the following branches: + ++ master:: the current accepted changes that will be in the next release ++ bug-:: changes addressing bug , shepherded by ++ rra:: old history of Russ's arch repository, now frozen ++ srivasta:: old history of Manoj's arch repository + +** Managing a bug + +The process used by Policy team members to manage a bug, once there is +proposed wording, is: + ++ Create a bug- branch for the bug, where is + the bug number in the BTS and is a designator of the Policy + team member who is shepherding the bug. ++ Commit wording changes in that branch until consensus is + achieved. Do not modify debian/changelog or upgrading-checklist.html + during this phase. Use the BTS to track who proposed the wording and + who seconded it. ++ git pull master to make sure you have the latest version. ++ Once the change has been approved by enough people, git merge the + branch into master immediately after making the final commit adding + the changelog entry to minimize conflicts. ++ add the debian/changelog and upgrading-checklist.html changes, and + commit to master. ++ Push master out so other people may merge in their own bug branches + without conflicts. ++ Tag the bug as pending and remove other process tags. ++ Delete the now-merged branch. + +The Git commands used for this workflow are: +#+BEGIN_SRC Sh +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.html +git add debian/changelog upgrading-checklist.html +git commit +git push origin master +git branch -d bug12345-rra +git push origin :bug12345-rra +#+END_SRC + +For the debian/changelog entry, use the following format: +#+BEGIN_EXAMPLE + * : + Wording: + Seconded: + Seconded: + Closes: +#+END_EXAMPLE + +For example: +#+BEGIN_EXAMPLE + * Policy: better document version ranking and empty Debian revisions + Wording: Russ Allbery + Seconded: Raphaël Hertzog + Seconded: Manoj Srivastava + Seconded: Guillem Jover + Closes: #186700, #458910 +#+END_EXAMPLE + +** Updating branches + +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: + +#+BEGIN_SRC Sh +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 +#+END_SRC + +assuming that you haven't packed the refs in your repository. + +** Making a release + +For a final Policy release, change UNRELEASED to unstable in +debian/changelog and update the timestamp to match the final release +time (dch -r may be helpful for this), update the release date in +upgrading-checklist.html, update Standards-Version in debian/control, +and commit that change. Then do the final release build and make sure +that it builds and installs. + +Then, tag the repository and push the final changes to Alioth: + +#+BEGIN_SRC Sh +git tag -s v3.8.0.0 +git push origin +git push --tags origin +#+END_SRC + +replacing the version number with the version of the release, of course. + +Finally, announce the new Policy release on debian-devel-announce, +including in the announcement the upgrading-checklist section for the +new release. + +** Setting release goals + +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: + ++ Proposing new language to address the bug that's seconded and approved by + the readers of the Policy list following the [[./Progress.org][Policy changes process]] (or + that's accepted by one of the Policy delegates if the change isn't + normative; i.e., doesn't change the technical meaning of the document). ++ Determining that the bug is not relevant to Policy and closing it. ++ Determining that either there is no consensus that the bug indicates + a problem, that the solutions that we can currently come up with are + good solutions, or that Debian is ready for the change. These bugs + are tagged wontfix and then closed after a while. A lot of Policy + bugs fall into this category; just because it would be useful to + have a policy in some area doesn't mean that we're ready to make + one, and keeping the bugs open against Policy makes it difficult to + tell what requires work. If the problem is worth writing a policy + for, it will come up again later when hopefully the project + consensus is more mature. + +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. diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..55e9b23 --- /dev/null +++ b/README.txt @@ -0,0 +1,346 @@ + Debian Policy + ============= + +Author: Manoj Srivastava And Russ Allbery +Date: 2009-09-15 15:48:35 CDT + + +Infrastructure +~~~~~~~~~~~~~~~ + ++ Website:: [http://www.debian.org/doc/devel-manuals#policy] ++ Mailing list:: debian-policy@lists.debian.org lists ++ Source Code:: + * git clone git://git.debian.org/git/dbnpolicy/policy.git + * Browser: [http://git.debian.org/?p=dbnpolicy/policy.git] ++ Unix group:: dbnpolicy ++ Alioth Project:: [http://alioth.debian.org/projects/dbnpolicy] (exists + to manage the repository but not otherwise used) + +Interacting with the team +========================== + ++ Email contact:: [mailto:debian-policy@lists.debian.org] ++ Request tracker:: [http://bugs.debian.org/src:debian-policy] + +Debian Policy uses a formal procedure and a set of user tags to manage +the lifecycle 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]. + +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://git.debian.org/git/dbnpolicy/policy.git + git checkout -b + + # edit files, but don't make changes to upgrading-checklist or debian/changelog + git add + git commit + # repeat as necessary + + # update your branch against the current master + git checkout master + git pull + + # If there are changes in master that make the branch not apply cleanly: + git checkout -b temp master; git merge + # If error, reset temp, merge master into local; else skip these three lines + git reset --hard HEAD; + git checkout ; + git merge master + # get rid of the temp branch: + git branch -D temp + + # Checkout the local branch, to create the patch to send to the policy + git checkout + dir=$(mktemp -d) + git format-patch -o $dir -s master + # check out the patches created in $dir + git send-email --from "you " \ + --to debian-policy@lists.debian.org \ + $dir/ + + + 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. + + +[Policy changes process]: Process.txt + +Usual Roles +~~~~~~~~~~~~ + +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: + ++ Russ Allbery ++ Bill Allombert ++ Andrew McMillan ++ Manoj Srivastava ++ Colin Watson (cjwatson) + +The special tasks of Policy delegates are: + ++ Commit access to the Git repository and uploads of the debian-policy + package itself, which makes them responsible for debian-policy as a + package in Debian and for making final decisions about when a new + version is released and what bits go into it. ++ Rejecting proposals. Anyone can argue against a proposal, but only + Policy delegates can formally reject it. ++ Counting seconds and weighing objections to proposals to determine + whether the proposal has sufficient support to be included. + +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. + +Task description +~~~~~~~~~~~~~~~~~ + +The Debian Policy team is responsible for maintaining and coordinating +updates to the technical Policy manuals for the project. The primary +output of the team is the Debian Policy Manual and the assorted +subpolicies, released as the debian-policy Debian package and also +published at [http://www.debian.org/doc/]. + +In addition to the main technical manual, the team currently also maintains: + ++ [Debian Menu sub-policy] ++ [Debian Perl Policy] ++ [Debian MIME support sub-policy] ++ [Debconf Specification] ++ [Authoritative list of virtual package names ] + +These documents are maintained using the [Policy changes process], and +the current state of all change proposals is tracked using the +[debian-policy BTS]. + + +[Debian Menu sub-policy]: http://www.debian.org/doc/packaging-manuals/menu-policy/ +[Debian Perl Policy]: http://www.debian.org/doc/packaging-manuals/perl-policy/ +[Debian MIME support sub-policy]: http://www.debian.org/doc/packaging-manuals/mime-policy/ +[Debconf Specification]: http://www.debian.org/doc/packaging-manuals/debconf_specification.html +[Authoritative list of virtual package names ]: http://www.debian.org/doc/packaging-manuals/virtual-package-names-list.txt +[Policy changes process]: Process.txt +[debian-policy BTS]: http://bugs.debian.org/src:debian-policy + +Get involved +~~~~~~~~~~~~~ + +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 [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: + ++ Policy is currently maintained in DebianDoc-SGML, which is no longer + very actively maintained and isn't a widely used or understood + format. The most logical replacement would be DocBook. However, + DocBook is a huge language with many tags and options, making it + rather overwhelming. We badly need someone with DocBook experience + to write a style guide specifying exactly which tags should be used + and what they should be used for so that we can limit ourselves to + an easy-to-understand and documented subset of the language. ++ Policy contains several appendices which are really documentation of + how parts of the dpkg system works rather than technical + Policy. Those appendices should be removed from the Policy document + and maintained elsewhere, probably as part of dpkg, and any Policy + statements in them moved into the main document. This project will + require reviewing the current contents of the appendices and feeding + the useful bits that aren't currently documented back to the dpkg + team as documentation patches. ++ Policy has grown organically over the years and suffers from + organizational issues because of it. It also doesn't make use of the + abilities that a current XML language might give us, such as being + able to extract useful portions of the document (all *must* + directives, for example). There has been quite a bit of discussion + of a new format that would allow for this, probably as part of + switching to DocBook, but as yet such a reorganization and reworking + has not been started. + +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. + + +[current open bugs]: http://bugs.debian.org/src:debian-policy +[debian-policy@lists.debian.org]: mailto:debian-policy@lists.debian.org +[Policy changes process]: Process.txt +[debian-policy@lists.debian.org ]: mailto:debian-policy@lists.debian.org + +Maintenance procedures +======================= + +Repository layout +================== + +The Git repository used for Debian Policy has the following branches: + ++ master:: the current accepted changes that will be in the next release ++ bug-:: changes addressing bug , shepherded by ++ rra:: old history of Russ's arch repository, now frozen ++ srivasta:: old history of Manoj's arch repository + +Managing a bug +=============== + +The process used by Policy team members to manage a bug, once there is +proposed wording, is: + ++ Create a bug- branch for the bug, where is + the bug number in the BTS and is a designator of the Policy + team member who is shepherding the bug. ++ Commit wording changes in that branch until consensus is + achieved. Do not modify debian/changelog or upgrading-checklist.html + during this phase. Use the BTS to track who proposed the wording and + who seconded it. ++ git pull master to make sure you have the latest version. ++ Once the change has been approved by enough people, git merge the + branch into master immediately after making the final commit adding + the changelog entry to minimize conflicts. ++ add the debian/changelog and upgrading-checklist.html changes, and + commit to master. ++ Push master out so other people may merge in their own bug branches + without conflicts. ++ Tag the bug as pending and remove other process tags. ++ Delete the now-merged branch. + +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 + # If there are changes in master that make the branch not apply cleanly: + git checkout -b temp master; git merge bug12345-rra + # If error; + git reset --hard HEAD; + git checkout bug12345-rra; git branch -D temp + git merge master + git checkout master + git merge bug12345-rra + # edit debian/changelog and upgrading-checklist.html + git add debian/changelog upgrading-checklist.html + 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: + * : + Wording: + Seconded: + Seconded: + Closes: + + +For example: + * Policy: better document version ranking and empty Debian revisions + Wording: Russ Allbery + Seconded: Raphaël Hertzog + Seconded: Manoj Srivastava + Seconded: Guillem Jover + Closes: #186700, #458910 + + +Updating branches +================== + +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. + +Making a release +================= + +For a final Policy release, change UNRELEASED to unstable in +debian/changelog and update the timestamp to match the final release +time (dch -r may be helpful for this), update the release date in +upgrading-checklist.html, update Standards-Version in debian/control, +and commit that change. Then do the final release build and make sure +that it builds and installs. + +Then, tag the repository and push the final changes to Alioth: + + git tag -s v3.8.0.0 + git push origin + git push --tags origin + + +replacing the version number with the version of the release, of course. + +Finally, announce the new Policy release on debian-devel-announce, +including in the announcement the upgrading-checklist section for the +new release. + +Setting release goals +====================== + +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: + ++ Proposing new language to address the bug that's seconded and approved by + the readers of the Policy list following the [Policy changes process] (or + that's accepted by one of the Policy delegates if the change isn't + normative; i.e., doesn't change the technical meaning of the document). ++ Determining that the bug is not relevant to Policy and closing it. ++ Determining that either there is no consensus that the bug indicates + a problem, that the solutions that we can currently come up with are + good solutions, or that Debian is ready for the change. These bugs + are tagged wontfix and then closed after a while. A lot of Policy + bugs fall into this category; just because it would be useful to + have a policy in some area doesn't mean that we're ready to make + one, and keeping the bugs open against Policy makes it difficult to + tell what requires work. If the problem is worth writing a policy + for, it will come up again later when hopefully the project + consensus is more mature. + +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. + +[Policy changes process]: ./Progress.org + diff --git a/debian/changelog b/debian/changelog index 445a12d..9afdef2 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,9 +1,31 @@ -debian-policy (3.8.3.1) UNRELEASED; urgency=low +debian-policy (3.8.4.1) UNRELEASED; urgency=low + + [ Colin Watson ] + * Fix path to changelog.Debian.gz in footnote on documentation symlinks. + + [ Bill Allombert ] + * Convert upgrading-checklist to debiandoc-sgml. This generates a better + looking .txt file. + Closes: #567845 + * Fix typo in package_upstream-version.orig.tar.gz. + Thanks, Salvatore Bonaccorso. (Closes: #558430) + + [ Russ Allbery ] + * Standardize dpkg state wording and bring it in line with dpkg, + renaming Failed-Config to Half-Configured and use uniform + capitalization and punctuation. (Closes: #442134) + + -- Bill Allombert Fri, 21 May 2010 21:02:34 +0200 + +debian-policy (3.8.4.0) unstable; urgency=low [ Bill Allombert ] * Also provide documents in single-file HTML format. Proposed by Jari Aalto. Closes: #544353 + * Number the DFSG points like in the social_contract document. + Proposed by Enrico Zini. + Closes: #550192 [ Manoj Srivastava ] * [b270d2d]: Typo fix: relayed -> related. Thanks to Matt Kraai for @@ -21,8 +43,56 @@ debian-policy (3.8.3.1) UNRELEASED; urgency=low Seconded: Russ Allbery Seconded: Giacomo A. Catenazzi Closes: #518199 - - -- Manoj Srivastava Mon, 05 Oct 2009 00:02:00 -0500 + * [8fd91a0] + README Process upgrading-checklist: Created/converted to org-mode + Wording: Manoj Srivastava + Seconded: Russ Allbery + Closes: #545548 + * [4da0692]: [typo-fixes]: + policy: Fix a number of grammatical or typographical errors + wording: Eric Dantan Rzewnicki + Seconded: Manoj Srivastava + * [112c4bc]: FHS Exceptions + policy: Explicitly allow /selinux and /sys as FHS exceptions + Wording: Manoj Srivastava + Seconded: Russ Allbery + Seconded: Kurt Roeckx + Closes: #556972 + This patch explicitly allows /sys and /selinux as additional + directories in the root file system allowed under the policy. + * [16afbcb]: Clarify ./debian/rules #! line + policy: Clarify rule for debian/rules shebang line + Wording: Ben Finney + Seconded: Kurt Roeckx + Seconded: Russ Allbery + Seconded: Manoj Srivastava + Explicitly state that "make -f debian/rules" and "./debian/rules" + must behave identically, to prevent confusion, and to promote + reproducibility, and conform to the principle of least surprise. + * [dab93b2]: Add a cron-daemon virtual package + policy, virtual package list: New virtual package: cron-daemon + wording: Javier Fernández-Sanguino Peña, Manoj Srivastava + Seconded: Russ Allbery + Seconded: Kurt Roeckx + Closes: #391836 + Create a virtual cron daemon package that: + - Has to provide /usr/bin/crontab and support crontab entries + - Correct execution of /etc/cron.d + - Correct support of /etc/crontab + - Support of crontab entries with names for days and months, + ranges, step values + - Correct execution of /etc/cron.{hourly,daily,weekly,monthly} + + [ Russ Allbery ] + * Policy: Clarify policy on named pipes in packages + Wording: Russ Allbery + Seconded: Manoj Srivastava + Seconded: Andrew McMillan + * Change the sole occurrence of MUST to must for consistency and to + avoid confusion with IETF RFC keywords. Thanks, Jakub Wilk. + (Closes: #552757) + + -- Bill Allombert Wed, 27 Jan 2010 19:22:43 +0100 debian-policy (3.8.3.0) unstable; urgency=low diff --git a/debian/control b/debian/control index 7f3c69c..897ab26 100644 --- a/debian/control +++ b/debian/control @@ -3,7 +3,7 @@ Section: doc Priority: optional Maintainer: Debian Policy List Uploaders: Manoj Srivastava , Russ Allbery , Colin Watson , Bill Allombert -Standards-Version: 3.8.3 +Standards-Version: 3.8.4 Build-Depends-Indep: sgml-data (>= 2.0), debiandoc-sgml (>= 1.1.47), texlive, texlive-latex-extra, groff, bsdmainutils, pstoedit, jade, docbook-xml (>= 3.1.1), docbook-dsssl, tidy, links (>= 0.90) | elinks Vcs-Browser: http://git.debian.org/?p=dbnpolicy/policy.git Vcs-Git: git://git.debian.org/git/dbnpolicy/policy.git diff --git a/debian/rules b/debian/rules index 07e635e..052193f 100755 --- a/debian/rules +++ b/debian/rules @@ -21,6 +21,15 @@ package := $(shell grep Source debian/control | sed 's/^Source: //') date := $(shell date +"%Y-%m-%d") version := $(shell awk -F '[()]' '/^$(package)/{ print $$2; exit }' debian/changelog) +# either /usr/bin/emacs-snampshot or /usr/bin/emacs23 +EMACS:=$(shell if [ -x /usr/bin/emacs-snapshot ]; then \ + echo /usr/bin/emacs-snapshot; \ + elif [ -x /usr/bin/emacs23 ]; then \ + echo /usr/bin/emacs23; \ + fi) +HAVE_ORG_EMACS:=$(strip $(EMACS)) + + # Location of the source dir SRCTOP := $(CURDIR) TMPTOP := $(SRCTOP)/debian/tmp @@ -29,7 +38,7 @@ LIBDIR := $(TMPTOP)/usr/share/doc-base sanitycheck := debian/rules policy.sgml -SGML_FILES := policy menu-policy mime-policy perl-policy +SGML_FILES := policy menu-policy mime-policy perl-policy upgrading-checklist DESC_FILES := debian-policy debian-menu-policy debian-perl-policy \ debian-mime-policy debconf-spec fhs @@ -45,15 +54,16 @@ FHS_NEW_FILES := POLICY_FILES = $(SGML_FILES:=.sgml) $(SGML_FILES:=.txt.gz) \ virtual-package-names-list.txt \ - upgrading-checklist.txt libc6-migration.txt version.ent \ + libc6-migration.txt version.ent \ debconf_spec/debconf_specification.html \ debconf_spec/debconf_specification.txt.gz \ - policy.ps.gz policy.pdf.gz + policy.ps.gz policy.pdf.gz README.txt README.html \ + Process.txt Process.html # policy.{pdf,ps,tpt,txt} are generated files FILES_TO_CLEAN = debian/files debian/buildinfo debian/substvars \ debian/postinst debian/prerm \ - version.ent upgrading-checklist.txt \ + version.ent \ $(SGML_FILES:=.txt.gz) $(SGML_FILES:=.html.tar.gz) \ $(SGML_FILES:=-1.html) \ policy.pdf.gz policy.ps.gz \ @@ -61,6 +71,8 @@ FILES_TO_CLEAN = debian/files debian/buildinfo debian/substvars \ policy.pdf policy.ps policy.txt policy. \ body.tmp head.tmp policy.tpt +FILES_FROM_ORG := README.txt README.html + STAMPS_TO_CLEAN := stamp-policy stamp-build DIRS_TO_CLEAN := debian/tmp fhs $(SGML_FILES:=.html) @@ -71,14 +83,16 @@ make_directory := install -p -d -o root -g root -m 755 all build: stamp-build -stamp-build: version.ent $(sanitycheck) +stamp-build: version.ent $(sanitycheck) README.txt README.html \ + Process.txt Process.html $(MAKE) $(SGML_FILES:=.sgml.validate) \ $(SGML_FILES:=.html.tar.gz) \ $(SGML_FILES:=-1.html) \ $(SGML_FILES:=.txt.gz) \ policy.ps.gz policy.pdf.gz - links -dump upgrading-checklist.html | perl -pe 's/[\r\0]//g' > \ - upgrading-checklist.txt +ifneq (,$(strip $(HAVE_ORG_EMACS))) + $(MAKE) $(FILES_FROM_ORG) +endif $(MAKE) -C debconf_spec all touch stamp-build diff --git a/policy.sgml b/policy.sgml index 45d6643..1de2494 100644 --- a/policy.sgml +++ b/policy.sgml @@ -90,11 +90,10 @@ is used by, a significant number of packages, and therefore should not be changed without peer review. Package maintainers can then rely on this - interfaces not changing, and the package - management software authors need to ensure - compatibility with these interface - definitions. (Control file and changelog file - formats are examples.) + interface not changing, and the package management + software authors need to ensure compatibility with + this interface definition. (Control file and + changelog file formats are examples.) Chosen Convention @@ -366,7 +365,7 @@ The Debian Free Software Guidelines (DFSG) form our definition of "free software". These are: - Free Redistribution + 1. Free Redistribution The license of a Debian component may not restrict any @@ -376,20 +375,20 @@ sources. The license may not require a royalty or other fee for such sale. - Source Code + 2. Source Code The program must include source code, and must allow distribution in source code as well as compiled form. - Derived Works + 3. Derived Works The license must allow modifications and derived works, and must allow them to be distributed under the same terms as the license of the original software. - Integrity of The Author's Source Code + 4. Integrity of The Author's Source Code The license may restrict source-code from being @@ -404,13 +403,13 @@ Project encourages all authors to not restrict any files, source or binary, from being modified.) - No Discrimination Against Persons or Groups + 5. No Discrimination Against Persons or Groups The license must not discriminate against any person or group of persons. - No Discrimination Against Fields of Endeavor + 6. No Discrimination Against Fields of Endeavor The license must not restrict anyone from making use @@ -419,7 +418,7 @@ used in a business, or from being used for genetic research. - Distribution of License + 7. Distribution of License The rights attached to the program must apply to all @@ -427,7 +426,7 @@ for execution of an additional license by those parties. - License Must Not Be Specific to Debian + 8. License Must Not Be Specific to Debian The rights attached to the program must not depend on @@ -439,7 +438,7 @@ rights as those that are granted in conjunction with the Debian system. - License Must Not Contaminate Other Software + 9. License Must Not Contaminate Other Software The license must not place restrictions on other @@ -448,7 +447,7 @@ that all other programs distributed on the same medium must be free software. - Example Licenses + 10. Example Licenses The "GPL," "BSD," and "Artistic" licenses are examples of @@ -1726,14 +1725,17 @@

It must start with the line #!/usr/bin/make -f, so that it can be invoked by saying its name rather than - invoking make explicitly. + invoking make explicitly. That is, invoking + either of make -f debian/rules args... + or ./debian/rules args... must result in + identical behavior.

Since an interactive debian/rules script makes it impossible to auto-compile that package and also makes it hard for other people to reproduce the same binary - package, all required targets MUST be + package, all required targets must be non-interactive. At a minimum, required targets are the ones called by dpkg-buildpackage, namely, clean, binary, binary-arch, @@ -2690,7 +2692,7 @@ Package: libc6 Priority

- This field represents how important that it is that the user + This field represents how important it is that the user have the package installed. See .

@@ -2823,8 +2825,8 @@ Package: libc6

- See for information how to get the - architecture for the build process. + See for information on how to get + the architecture for the build process.

@@ -2885,8 +2887,8 @@ Package: libc6

Thus only the first three components of the policy version are significant in the Standards-Version control - field, and so either these three components or the all - four components may be specified. + field, and so either these three components or all four + components may be specified. In the past, people specified the full version number in the Standards-Version field, for example "2.3.0.0". Since minor patch-level changes don't introduce new @@ -3278,7 +3280,7 @@ Package: libc6 for the most recent version should be returned first, and entries should be separated by the representation of a blank line (the "title" line may also be followed by the - representation of blank line). + representation of a blank line).

@@ -3394,7 +3396,7 @@ Files: no new original source archive is being distributed the .dsc must still contain the Files field entry for the original source archive - package-upstream-version.orig.tar.gz, + package_upstream-version.orig.tar.gz, but the .changes file should leave it out. In this case the original source archive on the distribution site must match exactly, byte-for-byte, the original @@ -3737,7 +3739,7 @@ Files: If this works, then the old-version is "Installed", if not, the old version is in a - "Failed-Config" state. + "Half-Configured" state.
@@ -3845,7 +3847,7 @@ Files: If this fails, the package is left in a "Half-Installed" state, which requires a reinstall. If it works, the packages is left in - a "Config Files" state. + a "Config-Files" state. Otherwise (i.e., the package was completely purged): @@ -3857,7 +3859,7 @@ Files: new-postrm abort-install If the error-unwind fails, the package is in a - "Half Installed" phase, and requires a + "Half-Installed" phase, and requires a reinstall. If the error unwind works, the package is in a not installed state. @@ -3937,14 +3939,14 @@ Files: old-preinst abort-upgrade new-version - If this fails, the old version is left in an - "Half Installed" state. If it works, dpkg now + If this fails, the old version is left in a + "Half-Installed" state. If it works, dpkg now calls: new-postrm abort-upgrade old-version - If this fails, the old version is left in an - "Half Installed" state. If it works, dpkg now + If this fails, the old version is left in a + "Half-Installed" state. If it works, dpkg now calls: old-postinst abort-upgrade new-version @@ -4103,7 +4105,7 @@ Files:

- If this fails, the package is in a "Failed-Config" + If this fails, the package is in a "Half-Configured" state, or else it remains "Installed".

@@ -4456,12 +4458,12 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any] be unpacked the pre-dependency can be satisfied if the depended-on package is either fully configured, or even if the depended-on - package(s) are only unpacked or half-configured, - provided that they have been configured correctly at - some point in the past (and not removed or partially - removed since). In this case, both the + package(s) are only unpacked or in the "Half-Configured" + state, provided that they have been configured + correctly at some point in the past (and not removed + or partially removed since). In this case, both the previously-configured and currently unpacked or - half-configured versions must satisfy any version + "Half-Configured" versions must satisfy any version clause in the Pre-Depends field.

@@ -4518,7 +4520,7 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]

A package will not be regarded as causing breakage merely because its configuration files are still installed; it must - be at least half-installed. + be at least "Half-Installed".

@@ -4572,7 +4574,7 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]

A package will not cause a conflict merely because its configuration files are still installed; it must be at least - half-installed. + "Half-Installed".

@@ -5378,10 +5380,10 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \

- If you are creating a udeb for use in the Debian Installer, you - will need to specify that dpkg-shlibdeps should use - the dependency line of type udeb by adding - -tudeb as option + If you are creating a udeb for use in the Debian Installer, + you will need to specify that dpkg-shlibdeps + should use the dependency line of type udeb by + adding the -tudeb option dh_shlibdeps from the debhelper suite will automatically add this option if it knows it is processing a udeb. @@ -5680,6 +5682,15 @@ libbar 1 bar1 (>= 1.0-1) symlinked there, is relaxed to a recommendation.

+ +

+ The following directories in the root filesystem are + additionally allowed: /sys and + /selinux. These directories + are used as mount points to mount virtual filesystems + to get access to kernel information. +

+

@@ -5725,13 +5736,15 @@ libbar 1 bar1 (>= 1.0-1)

- Note, that this applies only to directories below - /usr/local, not in /usr/local. - Packages must not create sub-directories in the directory - /usr/local itself, except those listed in FHS, - section 4.5. However, you may create directories below - them as you wish. You must not remove any of the - directories listed in 4.5, even if you created them. + Note that this applies only to + directories below /usr/local, + not in /usr/local. Packages must + not create sub-directories in the + directory /usr/local itself, except those + listed in FHS, section 4.5. However, you may create + directories below them as you wish. You must not remove + any of the directories listed in 4.5, even if you created + them.

@@ -5792,9 +5805,10 @@ rmdir /usr/local/share/emacs 2>/dev/null || true The system-wide mail directory

- The system-wide mail directory is /var/mail. This - directory is part of the base system and should not owned - by any particular mail agents. The use of the old + The system-wide mail directory + is /var/mail. This directory is part of the + base system and should not be owned by any particular mail + agents. The use of the old location /var/spool/mail is deprecated, even though the spool may still be physically located there.

@@ -6579,13 +6593,48 @@ Reloading description configuration...done. anacron. Thus, you should only use this directory for jobs which may be skipped if the system is not running.)

+

+ Unlike crontab files described in the IEEE Std + 1003.1-2008 (POSIX.1) available from + , the files in + /etc/cron.d and the file + /etc/crontab have seven fields; namely: + + Minute [0,59] + Hour [0,23] + Day of the month [1,31] + Month of the year [1,12] + Day of the week ([0,6] with 0=Sunday) + Username + Command to be run + + Ranges of numbers are allowed. Ranges are two numbers + separated with a hyphen. The specified range is inclusive. + Lists are allowed. A list is a set of numbers (or ranges) + separated by commas. Step values can be used in conjunction + with ranges. +

- The scripts or crontab entries in these directories should + The scripts or crontab entries in these directories should check if all necessary programs are installed before they try to execute them. Otherwise, problems will arise when a package was removed but not purged since configuration files - are kept on the system in this situation.

+ are kept on the system in this situation. +

+ +

+ Any cron daemon must provide + /usr/bin/crontab and support normal + crontab entries as specified in POSIX. The daemon + must also support names for days and months, ranges, and + step values. It has to support /etc/crontab, + and correctly execute the scripts in + /etc/cron.d. The daemon must also correctly + execute scripts in + /etc/cron.{hourly,daily,weekly,monthly}. +

@@ -7295,8 +7344,8 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq Device files

- Packages must not include device files in the package file - tree. + Packages must not include device files or named pipes in the + package file tree.

@@ -7321,6 +7370,18 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq /dev/cu* devices should be changed to use /dev/ttyS*.

+ +

+ Named pipes needed by the package must be created in + the postinst script + It's better to use mkfifo rather + than mknod to create named pipes so that + automated checks for packages incorrectly creating device + files with mknod won't have false positives. + and removed in + the prerm or postrm script as + appropriate. +

@@ -8669,9 +8730,9 @@ name ["syshostname"]:

Customization of programs' X resources may also be supported with the provision of a file with the same name - as that of the package placed in the - /etc/X11/Xresources/ directory, which must - registered as a conffile or handled as a + as that of the package placed in + the /etc/X11/Xresources/ directory, which + must be registered as a conffile or handled as a configuration file. Note that this mechanism is not the same as using app-defaults; app-defaults are tied to the client @@ -9055,7 +9116,7 @@ END-INFO-DIR-ENTRY

Please note that this does not override the section on changelog files below, so the file - /usr/share/package/changelog.Debian.gz + /usr/share/doc/package/changelog.Debian.gz must refer to the changelog for the current version of package in question. In practice, this means that the sources of the target and the destination of the diff --git a/upgrading-checklist.html b/upgrading-checklist.html deleted file mode 100644 index 11e81c4..0000000 --- a/upgrading-checklist.html +++ /dev/null @@ -1,723 +0,0 @@ - - - - - - - Policy checklist for upgrading your packages - - - -

Policy checklist for upgrading your packages

- -

About the checklist

- -

-The checklist below has been created to simplify the upgrading process -of old packages. Note that this list is not `official'; it simply -gives an indication of what has changed and whether you are likely to -need to make changes to your package in light of this. If you have -doubts about a certain topic, if you need more details, or if you -think some other package does not comply with policy, please refer to -the Policy Manual itself. All of the changes from version 3.0.0 -onwards indicate which section of the Policy Manual discusses the -issue: [3.4] means section 3.4. The section numbering changed when -the packaging manual was incorporated into policy; the section numbers -used below refer to the current version. -

- -

-Here is how the check list works: Check which policy version your -package complies with currently (indicated in the "Standards-Version" -field of the source package). Then move upwards until the top and -check which of the items on the list might concern your package. Note -which sections of policy discuss this, and then check out the Policy -Manual for details. If you are upgrading from Policy version < 2.5.0, -it may be easier to check through the whole of policy instead of -picking your way through this list. -

- -

The checklist

- -
-3.8.3.0                        Aug 2009
-
-     * Add DEB_*_ARCH_CPU and DEB_*_ARCH_OS variables and recommend them
-       over GNU-style variables for that information.            [4.9]
-     * Source package Architecture fields may contain "all" in combination
-       with other architectures.  Clarify when "all" and "any" may be used
-       in different versions of the field.                       [5.6.8]
-     * The Debian archive software does not support uploading to multiple
-       distributions with one *.changes file.                    [5.6.14]
-     * The Binary field may span multiple lines.                 [5.6.19]
-     * Remove the permission for shared library packages to install
-       libraries in a non-standard location and modify ld.so.conf.
-       Packages should either be installed in a standard library directory
-       or packages using them should be built with RPATH.        [10.2]
-     * Clarify installation directories for X programs and remove the
-       requirement to pre-depend on x11-common before installing into
-       /usr/include/X11 and /usr/lib/X11.                        [11.8.7]
-     * Remove the requirement that all characters in a manual page be
-       representable in the legacy encoding for that language.   [12.1]
-     * Localized man pages should either be kept up-to-date with the
-       original version or warn that they're not up-to-date, either with
-       warning text or by showing missing or changed portions in the
-       original language.                                        [12.1]
-     * install-info is now handled via triggers so packages no longer need
-       to invoke it in maintainer scripts.  Info documents should now have
-       directory sections and entries in the document.  Packages
-       containing info documents should add a dependency to support
-       partial upgrades.                                         [12.2]
-     * The requirement for Perl modules to have a versioned Depend and
-       Build-Depend on perl >= 5.6.0-16 has been removed.        [perl]
-
-3.8.2.0                        Jun 2009
-
-     * The list of archive sections has been significantly expanded.  See
-       http://lists.debian.org/debian-devel-announce/2009/03/msg00010.html
-       for the list of new sections and rules for how to categorize
-       packages.                                                 [2.4]
-     * All packages must use debconf or equivalent for user prompting,
-       though essential packages or their dependencies may also fall
-       back on other methods.                                    [3.9.1]
-     * The requirements for source package names are now explicitly
-       spelled out.                                              [5.6.1]
-     * Legacy XFree86 servers no longer get a special exception from the
-       FHS permitting /etc/X11/XF86Config-4.                     [9.1]
-     * Removed obsolete dependency requirements for packages that use
-       /var/mail.                                                [9.1.3]
-     * Speedo fonts are now deprecated.  The X backend was disabled
-       starting in lenny.                                        [11.8.5]
-     * The GNU Free Documentation License version 1.3 is included in
-       common-licenses and should be referenced from there.      [12.5]
-
-3.8.1.0                        Mar 2009
-
-     * Care should be taken when adding functionality to essential and
-       such additions create an obligation to support that functionality
-       in essential forever unless significant work is done.     [3.8]
-     * Changelog files must be encoded in UTF-8.                 [4.4]
-     * Tighten some format requirements for changelog files from a should
-       to a must.                                                [4.4]
-     * Remove alternative changelog formats.  Debian only supports one
-       changelog format for the Debian Archive.                  [4.4.1]
-     * New nocheck option for DEB_BUILD_OPTIONS indicating any build-time
-       test suite provided by the package should not be run.     [4.9.1]
-     * All control files must be encoded in UTF-8.               [5.1]
-     * debian/control allows comment lines starting with # with no
-       preceding whitespace.                                     [5.2]
-     * Init scripts ending in .sh are not handled specially.  They are not
-       sourced and are not guaranteed to be run by /bin/sh regardless of
-       the #! line.  This brings Policy in line with the long-standing
-       behavior of the init system in Debian.                    [9.3]
-     * The start action of an init script must exit successfully and not
-       start the daemon again if it's already running.           [9.3.2]
-     * /var/run and /var/lock may be mounted as temporary filesystems, and
-       init scripts must therefore create any necessary subdirectories
-       dynamically.                                              [9.3.2]
-     * /bin/sh scripts may assume that local can take multiple variable
-       arguments and supports assignment.                        [10.4]
-     * User mailboxes may be mode 600 and owned by the user rather than
-       mode 660, owned by user, and group mail.                  [11.6]
-
-3.8.0.0                        Jun 2008
-
-     * The base section has been removed.  contrib and non-free have been
-       removed from the section list; they are only categories.  The base
-       system is now defined by priority.                        [2.4, 3.7]
-     * If dpkg-source -x doesn't provide the source that will be compiled,
-       a debian/rules patch target is recommended and should do whatever
-       else is necessary.                                        [4.9]
-     * Standardized the format of DEB_BUILD_OPTIONS.  Specified permitted
-       characters for tags, required that tags be whitespace-separated,
-       allowed packages to assume non-conflicting tags, and required
-       unknown flags be ignored.                                 [4.9.1, 10.1]
-     * Added parallel=n to the standardized DEB_BUILD_OPTIONS tags,
-       indicating that a package should be built using up to n parallel
-       processes if the package supports it                      [4.9.1]
-     * Debian packages should not use convenience copies of code from other
-       packages unless the included package is explicitly intended to be
-       used that way.                                            [4.13]
-     * If dpkg-source -x doesn't produce source ready for editing and
-       building with dpkg-buildpackage, packages should include a
-       debian/README.source file explaining how to generate the patched
-       source, add a new modification, and remove an existing
-       modification.  This file may also be used to document packaging a
-       new upstream release and any other complexity of the Debian build
-       process.                                                  [4.14]
-     * The Uploaders field in debian/control may be wrapped.     [5.6.3]
-     * An empty Debian revision is equivalent to a Debian revision of 0 in
-       a version number.                                         [5.6.12]
-     * New Homepage field for upstream web sites.                [5.6.23]
-     * The Breaks field declares that this package breaks another and
-       prevents installation of the breaking package unless the package
-       named in Breaks is deconfigured first.  This field should not be
-       used until the dpkg in Debian stable supports it.         [6.5, 6.6, 7]
-     * Clarify which files should go into a shared library package, into a
-       separate package, or into the -dev package.  Suggest -tools instead
-       of -runtime for runtime support programs, since that naming is more
-       common in Debian.                                         [8.1, 8.2]
-     * Files in /etc/cron.{hourly,daily,weekly,monthly} must be
-       configuration files (upgraded from should).  Mention the hourly
-       directory.                                                [9.5]
-     * Packages providing /etc/X11/Xresources files need not conflict with
-       xbase (<< 3.3.2.3a-2), which is long-obsolete.            [11.8.6]
-     * Manual pages in locale-specific directories should use either the
-       legacy encoding for that directory or UTF-8.  Country names should
-       not be included in locale-specific manual page directories unless
-       indicating a significant difference in the language.  All
-       characters in the manual page source should be representable in the
-       legacy encoding for a locale even if the man page is encoded in
-       UTF-8.                                                    [12.1]
-     * The Apache 2.0 license is now in common-licenses and should be
-       referenced rather than quoted in debian/copyright.        [12.5]
-     * Packages in contrib and non-free should state in the copyright file
-       that the package is not part of Debian GNU/Linux and briefly
-       explain why.                                              [12.5]
-     * Underscore (_) is allowed in debconf template names.      [debconf]
-
-3.7.3.0                        Dec 2007
-
-     * Package version numbers may contain tildes, which sort before
-       anything, even the end of a part.                         [5.6.12]
-     * Scripts may assume that /bin/sh supports local (at a basic level)
-       and that its test builtin (if any) supports -a and -o binary
-       logical operators.                                        [10.4]
-     * The substitution variable ${binary:Version} should be used in place
-       of ${Source-Version} for dependencies between packages of the same
-       library.                                                  [8.5]
-     * Substantial reorganization and renaming of sections in the Debian
-       menu structure.  Packages with menu entries should be reviewed to
-       see if the menu section has been renamed or if one of the new
-       sections would be more appropriate.                       [menu policy]
-     * The Source field in a .changes file may contain a version number
-       in parentheses.                                           [5.6.1]
-     * The acceptable values for the Urgency field are low, medium, high,
-       critical, or emergency.                                   [5.6.17]
-     * The shlibs file now allows an optional type field, indicating the
-       type of package for which the line is valid.  The only currently
-       supported type is udeb, used with packages for the Debian
-       Installer.                                                [8.6]
-     * Packages following the Debian Configuration management
-       specification must allow for translation of their messages by using
-       a gettext-based system such as po-debconf.                [3.9.1]
-     * GFDL 1.2, GPL 3, and LGPL 3 are now in common-licenses and should
-       be referenced rather than quoted in debian/copyright.     [12.5]
-
-3.7.2.2                        Oct 2006
-
-     * Maintainer scripts must not be world writeable (up from a
-       should to a must)                                         [6.1]
-
-3.7.2.0                        Apr 2006
-
-     * Revert the cgi-lib change.                                [11.5]
-
-3.7.1.0                        Apr 2006
-
-     * It is now possible to create shared libraries without
-       relocatable code (using -fPIC) in certain exceptional cases,
-       provided some procedures are followed, and for creating static
-       libraries with relocatable code (again, using -fPIC).
-       Discussion on debian-devel@lists.debian.org, getting a rough
-       consensus, and documenting it in README.Debian constitute most
-       of the process.                                           [10.2]    
-     * Packages should install any relevant files into the directories
-       /usr/include/X11/and /usr/lib/X11/, but if they do so, they
-       must  pre-depend on x11-common (>= 1:7.0.0)              [11.8.7] 
-
-3.7.0.0                        Apr 2006
-
-     * Packages shipping web server CGI files are expected to install
-       them in /usr/lib/cgi-lib/ directories.  This location change
-       perhaps should be documented in NEWS                      [11.5]
-     * Web server packages should include a standard scriptAlias of
-       cgi-lib to /usr/lib/cgi-lib.                              [11.5]
-     * The version of FHS mandated by policy has been upped to
-       2.3. There should be no changes required for most packages,
-       though new top level directories /media, /srv, etc may be of
-       interest.                                                 [9.1.1]
-     * All fields, apart from the Uploaders field, in the control file
-       are supposed to be a single logical line, which may be spread
-       over multiple physical  lines (newline followed by space is
-       elided).  However, any parser for the control file must allow
-       the Uploaders field to be spread over multiple physical lines
-       as well, to prepare for future changes.                 [ 5.1, 5.6.3 ]
-     * When scripts are installed into a directory in the system
-       PATH, the script name should not include an extension that
-       denotes the scripting language currently used to implement it.
-                                                              [ 10.4 ]
-     * packages that invoke initscripts now must use invoke-rc.d to do
-       so since it also pays attention to run levels and other local
-       constraints.                                                [ 9.3.3.2 ]
-     * We no longer use /usr/X11R6, since we have migrated away to
-       using Xorg paths. This means, for one thing, fonts live in
-       /usr/share/fonts/X11/ now, and /usr/X11R6 is gone.
-                                                      [ 11.8.5.2, 11.8.7, etc]
-
-3.6.2.0                        2005
-
-     * Recommend doc-base, and not menu, for registering package documentation.
-     * Run time support programs should live in subdirectories of
-       /usr/lib/ or /usr/share, and preferably the shared lib is named
-       the same as the package name (to avoid name collisions). [8.1]
-     * It is recommended that HTTP servers provide an alias /images to
-       allow packages to share image files with the web server [11.5]
-
-3.6.1.0                    Aug 2003
-
-     + Prompting the user should be done using debconf. Non debconf
-       user prompts are now deprecated. [3.10.1]
-
-3.6.0                      Jul 2003
-
-     - Restructuring causing shifts in section numbers and bumping of
-       the minor version number:
-     + Many packaging manual appendices that were integrated into policy
-       sections are now empty, and replaced with links to the Policy.
-       In particular, the appendices that included the list of control
-       fields were updated (new fields like Closes, Changed-By were added)
-       and the list of fields for each of control, .changes and .dsc files
-       is now in Policy, and they're marked mandatory, recommended or
-       optional based on the current practice and the behavior of the
-       deb-building tool-chain.
-     + Elimination of needlessly deep section levels, primarily in the
-       chapter Debian Archive, from which two new chapters were split out,
-       Binary packages and Source packages. What remained was reordered
-       properly, that is, some sect1s became sects etc.
-     + Several sections that were redundant, crufty or simply not designed
-       with any sort of vision, were rearranged according to the formula that
-       everything should be either in the same place or properly interlinked.
-       Some things remained split up between different chapters when they
-       talked about different aspects of files: their content, their syntax,
-       and their placement in the file system. In particular, see the new
-       sections about changelog files.
-     - Added Games/Simulation and Apps/Education to menu sub-policy
-       [menu policy]
-     - Debian changelogs should be UTF-8 encoded. [C.2.2]
-     - shared libraries must be linked against all libraries that they
-       use symbols from in the same way that binaries are. [10.2]
-     - build-depends-indep need not be satisfied during clean
-       target. [7.6] 
-
-3.5.10                     May 2003
-
-     - packages providing the x-terminal-emulator virtual package
-       ought to ensure that they interpret the command line exactly
-       like xterm does. [11.8.3]
-     - Window managers compliant with the Window Manager Specification
-       Project may add 40 points for ranking in the alternatives [11.8.4]
-
-3.5.9.0                    Mar 2003
-
-     - The section describing the Description: package field once again has
-       full details of the long description format. [3.4.2]
-     - Clarified that if a package has non-build-essential
-       build-dependencies, it should have them listed in the Build-Depends
-       and related fields (i.e. it's not merely optional). [4.2]
-     - When asked to restart a service that isn't already running,
-       the init script should start the service. [9.3.2]
-     - If the purpose of a package is to provide examples, then the
-       example files can be installed into /usr/share/doc/package
-       (rather than /usr/share/doc/package/examples). [12.6]
-
-3.5.8.0                    Nov 2002
-
-     - It is no longer necessary to keep a log of changes to the upstream
-       sources in the copyright file. Instead, all such changes should be
-       documented in the changelog file. [12.7]
-     - Build-Depends, 	Build-Conflicts,
-       Build-Depends-Indep, and
-       Build-Conflicts-Indep must also be satisfied when the
-       clean target is called. [7.6]
-     - A new Apps/Science menu section is available [menu policy]
-     - debconf specification cleared up, various changes. [debconf
-       policy]
-     - It is no longer recommended to create symlinks from nonexistent
-       manual pages to undocumented(7). Missing manual pages for programs
-       are still a bug. [12.1]
-
-3.5.7.0                    Aug 2002
-
-     - Packages no longer have to ask permission to call MAKEDEV in
-       postinst, merely notifying the user ought to be enough. [10.6]
-     - cryptographic software may now be included in the main
-       archive. [2.2.4]
-     - task packages are no longer permitted; tasks are now created by a
-       special Tasks: field in the control file. [3.9]
-     - window managers that support netwm can now add 20 points when
-       they add themselves as an alternative for
-       /usr/bin/x-window-manager [11.8.4]
-     - The default compilation options have now changed, one should
-       provide debugging symbols in all cases, and optionally step
-       back optimization to -O0, depending on the DEB_BUILD_OPTIONS
-       environment variable. [10.1]
-     - Added mention of build-arch, build-indep, etc, in describing
-       the relationships with `Build-Depends', `Build-Conflicts',
-       `Build-Depends-Indep', and `Build-Conflicts-Indep'. May need to
-       review the new rules.  [7.6, 4.8]
-     - Changed rules on how, and when, to invoke ldconfig in maintainer
-       scripts. Long rationale. [8]
-     - [Added the last note in 3.5.6 upgrading checklist item regarding
-       build rules, please see below]
-
-3.5.6.0                    Jul 2001
-
-     - Emacs and TeX are no longer mandated by policy to be priority
-       standard packages [2.5]
-     - Programs that access docs need to do so via /usr/share/doc, and
-       not via /usr/doc/ as was the policy previously [11.5]
-     - Putting documentation in /usr/doc versus /usr/share/doc is now
-       a ``serious'' policy violation. [12.3]
-     - For web servers, one should not provide non-local access to the
-       /usr/share/doc hierarchy. If one can't provide access controls for
-       the http://localhost/doc/ directory, then it is preferred that one
-       ask permission to expose that information during the install. [11.5]
-     - There are new rules for build-indep/build-arch targets and
-       there is a new Build-Depend-Indep semantic. [7]
-
-3.5.5.0                    May 2001
-
-     - Manpages should not rely on header information to have
-       alternative manpage names available; it should only use
-       symlinks or .so pages to do this [12.1]
-     - [Clarified note in 3.5.3.0 upgrading checklist regarding
-        examples and templates: this refers only to those examples used
-        by scripts; see section 10.7.3 for the whole story]
-     - Included a new section 10.9.1 describing the use of
-       dpkg-statoverride; this does not have the weight of policy
-     - Clarify Standards-Version: you don't need to rebuild your
-       packages just to change the Standards-Version!
-     - Plugins are no longer bound by all the rules of shared
-       libraries [10.2]
-     - X Windows related things:
-       * Clarification of priority levels of X Window System related
-         packages [11.8.1]
-       * Rules for defining x-terminal-emulator improved [11.8.3]
-       * X Font policy rewritten: you must read this if you provide
-         fonts for the X Window System [11.8.5]
-       * Packages must not ship /usr/X11R6/lib/X11/app-defaults/ [11.8.6]
-       * X-related packages should usually use the regular FHS
-         locations; imake-using packages are exempted from this [11.8.7]
-       * OpenMotif linked binaries have the same rules as
-         OSF/Motif-linked ones [11.8.8]
-
-3.5.4.0                    Apr 2001
-
-     - The system-wide mail directory is now /var/mail, no longer
-       /var/spool/mail.  Any packages accessing the mail spool should
-       access it via /var/mail and include a suitable Depends field;
-       details in [11.6]
-     - The perl policy is now part of Debian policy proper. Perl
-       programs and modules should follow the current Perl policy
-       [11.9; perl-policy]
-
-3.5.3.0                    Apr 2001
-
-     - Build-Depends arch syntax has been changed to be less
-       ambiguous. This should not affect any current packages [7.1]
-     - Examples and templates files for use by scripts should now live
-       in /usr/share/<package> or /usr/lib/<package>, with
-       symbolic links from /usr/share/doc/<package>/examples as
-       needed [10.7.3]
-
-3.5.2.0                    Feb 2001
-
-     - X app-defaults directory has moved from
-       /usr/X11R6/lib/X11/app-defaults to /etc/X11/app-defaults [11.8.6]
-
-3.5.1.0                    Feb 2001
-
-     - dpkg-shlibdeps now uses objdump, so shared libraries have to be
-       run through dpkg-shlibdeps as well as executables [8.1]
-
-3.5.0.0                    Jan 2001
-
-     - Font packages for the X Window System must now declare a
-       dependency on xutils (>= 4.0.2) [11.8.5]
-
-3.2.1.1                    Jan 2001
-
-     - Daemon startup scripts in /etc/init.d/ should not contain
-       modifiable parameters; these should be moved to a file in
-       /etc/default/; see [9.3.2] for details
-     - Files in /usr/share/doc must not be referenced by any
-       program.  If such files are needed, they must be placed in
-       /usr/share/<package>/, and symbolic links created as required
-       in /usr/share/doc/<package>/ [12.3]
-     - Much of the packaging manual has now been imported into the
-       policy document
-
-3.2.1.0                    Aug 00
-
-     - A package of priority standard or higher may provide two
-       binaries, one compiled with support for the X Window System,
-       and the other without [11.8.1]
-
-3.2.0.0                    Aug 00
-
-     - By default executables should not be built with the debugging
-       option -g. Instead, it is recommended to support building the
-       package with debugging information optionally.  Details in [10.1]
-     - Policy for packages where the upstream uses HTML changelog
-       files has been expanded.  In short, a plain text changelog file
-       should always be generated for the upstream changes [12.8]
-     - Please note that the new release of the X window system (3.2)
-       shall probably need sweeping changes in policy
-     - Policy for packages providing the following X-based features
-       has been codified:
-       - X server (virtual package xserver) [11.8.2]
-       - X terminal emulator (virtual package x-terminal-emulator) [11.8.3]
-       - X window manager (virtual package x-window-manager, and
-         /usr/bin/x-window-manager alternative, with priority
-         calculation guidelines) [11.8.4]
-       - X fonts (this section has been written from scratch) [12.8.5]
-       - X application defaults [11.8.6]
-     - Policy for packages using the X Window System and FHS issues
-       has been clarified; see [11.8.7]
-     - No package may contain or make hard links to conffiles [11.7.3]
-     - Noted that newer dpkg versions do not require extreme care in
-       always creating the shared lib before the symlink, so the unpack
-       order be correct [8]
-
-3.1.1.0                    Nov 1999
-
-     - Correction to semantics of architecture lists in Build-Depends
-       etc.  Should not affect many packages [7.1]
-
-3.1.0.0                    Oct 1999
-
-     - /usr/doc/<package> has to be a symlink pointing to
-       /usr/share/doc/<package>, to be maintained by postinst
-       and prerm scripts.  Details are in [defunct]
-     - Introduced source dependencies (Build-Depends, etc.) [7.1, 7.6]
-     - /etc/rc.boot has been deprecated in favour of /etc/rcS.d.
-       (Packages should not be touching this directory, but should use
-       update-rc.d instead) [9.3.4]
-     - update-rc.d is now the *only* allowable way of accessing the
-       /etc/rc?.d/[SK]??* links.  Any scripts which manipulate them
-       directly must be changed to use update-rc.d instead.  (This is
-       because the file-rc package handles this information in an
-       incompatible way.) [9.3.3]
-     - Architecture-specific examples go in /usr/lib/<package>/examples
-       with symlinks from /usr/share/doc/<package>/examples/* or from
-       /usr/share/doc/<package>/examples itself [12.7]
-     - Updated FHS to a 2.1 draft; this reverts /var/state to
-       /var/lib [9.1.1]
-     - Added MIME sub-policy document [9.7; mime-policy]
-     - VISUAL is allowed as a (higher priority) alternative to EDITOR [12.4]
-     - Modified liblockfile description, which affects
-       mailbox-accessing programs.  Please see the policy document for
-       details [11.6]
-     - If a package provides a changelog in HTML format, a text-only
-       version should also be included.  (Such a version may be prepared
-       using lynx -dump -nolist.) [12.7]
-     - Description of how to handle version numbers based on dates
-       added [3.2.1]
-
-3.0.1.0                    Jul 1999
-
-    -  Added the clarification that the .la files are essential for the
-       packages using libtool's libltdl library, in which case the
-       .la files must go in the run-time library package [10.2]
-
-3.0.0.0                    Jun 1999
-
-    - Debian formally moves from the FSSTND to the FHS. This is a
-      major change, and the implications of this move are probably
-      not all known. [9.1]
-    - Only 3 digits of the Standards version need be included in
-      control files, though all four digits are still permitted. [4.1]
-    - The location of the GPL has changed to
-      /usr/share/common-licenses. This may require changing the
-      copyright files to point to the correct location of the GPL and
-      other major licenses [12.6]
-    - Packages that use libtool to create shared libraries must
-      include the .la files in the -dev packages [10.2]
-    - Use logrotate to rotate log files [10.8]
-    - section 5.8 has been rewritten (Programs for the X Window
-      System) [now 11.8]
-    - There is now an associated menu policy, in a separate document,
-      that carries the full weight of Debian policy [9.6; menu-policy]
-    - Programs which need to modify the files /var/run/utmp,
-      /var/log/wtmp and /var/log/lastlog must be installed setgid utmp [11.3]
-
-
-** Please note that section numbers below this point may not be up to date **
-
-
-2.5.0.0                         Oct 1998
-
-  Policy Manual:
-    - Rearranged the manual to create a new Section 4, Files
-      + Section 3.3 ("Files") was moved to Section 4. The Sections
-        that  were Section 4 and Section 5 were  moved down to become
-        Section 5 and Section 6.
-      + What was Section 5.5 ("Log files") is now a subsection of the
-        new Section 4 ("Files"), becoming section 4.8, placed after
-        "Configuration files", moving the Section 4.8 ("Permissions
-        and owners") to Section 4.9.  All subsections of the old
-        Section 5 after 5.5  were moved down to fill in the number
-        gap.
-    - Modified the section about changelog files to accommodate
-      upstream changelogs which were formatted as HTML/ These
-      upstream changelog files should now be accessible as
-      /usr/doc/package/changelog.html.gz
-      + Symlinks are permissible to link the real, or upstream,
-        changelog name to the Debian mandated name.
-    - Clarified that HTML documentation should be present in some
-      package, though not necessarily the main binary package.
-    - Corrected all references to the location of the copyright
-      files. The correct location is /usr/doc/package/copyright
-    - Ratified the architecture specification strings to cater to the
-      HURD.
-
-2.4.1.0                         Apr 1998
-
-  Policy Manual:
-    - Updated section 3.3.5 Symbolic links:
-      + symbolic links within a toplevel directory should be relative,
-        symbolic links between toplevel directories should be absolute
-        (cf., Policy Weekly Issue#6, topic 2)
-
-    - Updated section 4.9 Games:
-      + manpages for games should be installed in /usr/man/man6
-        (cf., Policy Weekly Issue#6, topic 3)
-
-  Packaging Manual:
-    - Updated prefix of chapter 12, Shared Libraries:
-      ldconfig must be called in the postinst script if the package
-      installs shared libraries
-      (cf., Policy Weekly Issue #6, fixes:bug#20515)
-
-2.4.0.0                         Jan 1998
-
-    - Updated section 3.3.4 Scripts:
-      + /bin/sh may be any POSIX compatible shell
-      + scripts including bashisms have to specify /bin/bash as
-        interpreter
-      + scripts which create files in world-writable directories
-        (e.g., in /tmp) should use tempfile or mktemp for creating
-        the directory
-
-    - Updated section 3.3.5 Symbolic Links:
-      + symbolic links referencing compressed files must have the same
-        file extension as the referenced file
-
-    - Updated section 3.3.6 Device files:
-      + /dev/tty* serial devices should be used instead of /dev/cu*
-
-    - Updated section 3.4.2 Writing the scripts [in /etc/init.d]:
-      + all /etc/init.d scripts have to provide the following options:
-        start, stop, restart, force-reload
-      + the reload option is optional and must never stop and restart
-        the service
-
-    - Updated section 3.5 Cron jobs:
-      + cron jobs that need to be executed more often than daily should
-        be installed into /etc/cron.d
-
-    - Updated section 3.7 Menus:
-      + removed section about how to register HTML docs to `menu'
-        (the corresponding section in 4.4, Web servers and applications,
-        has been removed in policy 2.2.0.0 already, so this one was
-        obsolete)
-
-    - New section 3.8 Keyboard configuration:
-      + details about how the backspace and delete keys should be
-        handled
-
-    - New section 3.9 Environment variables:
-      + no program must depend on environment variables to get a
-        reasonable default configuration
-
-    - New section 4.6 News system configuration:
-      + /etc/news/organization and /etc/news/server should be supported
-        by all news servers and clients
-
-    - Updated section 4.7 Programs for the X Window System:
-      + programs requiring a non-free Motif library should be provided
-        as foo-smotif and foo-dmotif package
-      + if lesstif works reliably for such program, it should be linked
-        against lesstif and not against a non-free Motif library
-
-    - Updated section 4.9 Games:
-      + games for X Windows have to be installed in /usr/games, just as
-        non-X games
-
-2.3.0.1, 2.3.0.0		Sep 1997
-
-	* new section `4.2 Daemons' including rules for
-	  /etc/services, /etc/protocols, /etc/rpc, and /etc/inetd.conf
-
-	* updated section about `Configuration files':
-	  packages may not touch other packages' configuration files
-
-	* MUAs and MTAs have to use liblockfile
-
-2.2.0.0				Jul 1997
-
-	* added section 4.1 `Architecture specification strings':
-          use
-	       <arch>-linux
-          where <arch> is one of the following:
-               i386, alpha, arm, m68k, powerpc, sparc.
-
-	* detailed rules for /usr/local
-
-	* user ID's
-
-	* editor/pager policy
-
-	* cron jobs
-
-	* device files
-
-	* don't install shared libraries as executable
-
-	* app-defaults files may not be conffiles
-
-2.1.3.2, 2.1.3.1, 2.1.3.0	Mar 1997
-
-	* two programs with different functionality must not have the
-	  same name
-
-	* "Webstandard 3.0"
-
-	* "Standard for Console Messages"
-
-	* Libraries should be compiled with `-D_REENTRANT'
-
-	* Libraries should be stripped with "strip --strip-unneeded"
-
-2.1.2.2, 2.1.2.1, 2.1.2.0	Nov 1996
-
-	* Some changes WRT shared libraries
-
-2.1.1.0				Sep 1996
-
-	* No hard links in source packages
-
-	* Do not use dpkg-divert or update-alternatives without consultation
-
-	* Shared libraries must be installed stripped
-
-2.1.0.0				Aug 1996
-
-	* Upstream changelog must be installed too
-
- -
- - - - - diff --git a/upgrading-checklist.sgml b/upgrading-checklist.sgml new file mode 100644 index 0000000..5425cfc --- /dev/null +++ b/upgrading-checklist.sgml @@ -0,0 +1,1174 @@ + + + + + Policy checklist for upgrading your packages + Bill Allombert + Josip Rodin + Julian Gilbey + Russ Allbery + Manoj Srivastava About the checklist +

+The checklist below has been created to simplify the upgrading process +of old packages. Note that this list is not "official"; it simply +gives an indication of what has changed and whether you are likely to +need to make changes to your package in light of this. If you have +doubts about a certain topic, if you need more details, or if you +think some other package does not comply with policy, please refer to +the Policy Manual itself. All of the changes from version 3.0.0 +onwards indicate which section of the Policy Manual discusses the +issue: [3.4] means section 3.4. The section numbering changed when +the packaging manual was incorporated into policy; the section numbers +used below refer to the current version. +

+Here is how the check list works: Check which policy version your +package was checked against last (indicated in the "Standards-Version" +field of the source package). Then move upwards until the top and +check which of the items on the list might concern your package. Note +which sections of policy discuss this, and then check out the Policy +Manual for details. If you are upgrading from Policy version < 2.5.0, +it may be easier to check through the whole of policy instead of +picking your way through this list. + + The checklist + + Version 3.8.4.0 +

+ +Release Jan 2010. + +

+9.1.1 + An FHS exception has been granted for multiarch libraries. + Permitting files to instead be installed to /lib/triplet and + /usr/lib/triplet directories. + +10.6 + Explicitly state that packages may not contain named pipes and + should instead create them in postinst and remove them in prerm or postrm. + +9.1.1 + /sys and /selinux directories are explicitly + allowed as an exception to the FHS. + +

+ + Version 3.8.3.0 +

+Released Aug 2009. + +

+4.9 + Add DEB_*_ARCH_CPU and DEB_*_ARCH_OS variables and + recommend them over GNU-style variables for that information. + +5.6.8 + Source package Architecture fields may contain +5.6.14 + The Debian archive software does not support uploading + to multiple distributions with one *.changes file. + +5.6.19 + The Binary field may span multiple lines. + +10.2 + Remove the permission for shared library packages to + install libraries in a non-standard location and modify +11.8.7 + Clarify installation directories for X programs and + remove the requirement to pre-depend on x11-common before installing + into /usr/include/X11 and /usr/lib/X11. + +12.1 + Remove the requirement that all characters in a manual + page be representable in the legacy encoding for that language. + +12.1 + Localized man pages should either be kept up-to-date with + the original version or warn that they're not up-to-date, either + with warning text or by showing missing or changed portions in the + original language. + +12.2 + install-info is now handled via triggers so packages no + longer need to invoke it in maintainer scripts. Info documents + should now have directory sections and entries in the document. + Packages containing info documents should add a dependency to + support partial upgrades. + +perl + The requirement for Perl modules to have a versioned + Depend and Build-Depend on perl >= 5.6.0-16 has been removed. + +

+ + Version 3.8.2.0 +

+ +Released Jun 2009. + +

+2.4 + The list of archive sections has been significantly expanded. See + + for the list of new sections and rules for how to categorize + packages. + +3.9.1 + All packages must use debconf or equivalent for user prompting, + though essential packages or their dependencies may also fall + back on other methods. + +5.6.1 + The requirements for source package names are now explicitly + spelled out. + +9.1 + Legacy XFree86 servers no longer get a special exception from the + FHS permitting /etc/X11/XF86Config-4. + +9.1.3 + Removed obsolete dependency requirements for packages that use + /var/mail. + +11.8.5 + Speedo fonts are now deprecated. The X backend was disabled + starting in lenny. + +12.5 + The GNU Free Documentation License version 1.3 is included in + common-licenses and should be referenced from there. + +

+ + Version 3.8.1.0 +

+ +Released Mar 2009. + +

+3.8 + Care should be taken when adding functionality to essential and + such additions create an obligation to support that functionality + in essential forever unless significant work is done. + +4.4 + Changelog files must be encoded in UTF-8. + +4.4 + Tighten some format requirements for changelog files from a should + to a must. + +4.4.1 + Remove alternative changelog formats. Debian only supports one + changelog format for the Debian Archive. + +4.9.1 + New nocheck option for DEB_BUILD_OPTIONS indicating any build-time + test suite provided by the package should not be run. + +5.1 + All control files must be encoded in UTF-8. + +5.2 + debian/control allows comment lines starting with # with no + preceding whitespace. + +9.3 + Init scripts ending in .sh are not handled specially. They are not + sourced and are not guaranteed to be run by /bin/sh regardless + of the #! line. This brings Policy in line with the long-standing + behavior of the init system in Debian. + +9.3.2 + The start action of an init script must exit successfully and not + start the daemon again if it's already running. + +9.3.2 + /var/run and /var/lock may be mounted as + temporary filesystems, and init scripts must therefore create any necessary + subdirectories dynamically. + +10.4 + /bin/sh scripts may assume that local can take multiple + variable arguments and supports assignment. + +11.6 + User mailboxes may be mode 600 and owned by the user rather than + mode 660, owned by user, and group mail. + +

+ + Version 3.8.0.0 +

+ +Released Jun 2008. + +

+2.4, 3.7 +The base section has been removed. contrib and non-free have been + removed from the section list; they are only categories. The base + system is now defined by priority. +4.9 +If dpkg-source -x doesn't provide the source that will be + compiled, a debian/rules patch target is recommended and should do whatever + else is necessary. +4.9.1, 10.1 +Standardized the format of DEB_BUILD_OPTIONS. Specified permitted + characters for tags, required that tags be whitespace-separated, + allowed packages to assume non-conflicting tags, and required + unknown flags be ignored. +4.9.1 +Added parallel=n to the standardized DEB_BUILD_OPTIONS tags, + indicating that a package should be built using up to n parallel + processes if the package supports it +4.13 +Debian packages should not use convenience copies of code from other + packages unless the included package is explicitly intended to be + used that way. +4.14 +If dpkg-source -x doesn't produce source ready for editing and + building with dpkg-buildpackage, packages should include a + debian/README.source file explaining how to generate + the patched source, add a new modification, and remove an existing + modification. This file may also be used to document packaging a + new upstream release and any other complexity of the Debian build + process. +5.6.3 +The Uploaders field in debian/control may be wrapped. +5.6.12 +An empty Debian revision is equivalent to a Debian revision of 0 in + a version number. +5.6.23 +New Homepage field for upstream web sites. +6.5, 6.6, 7 +The Breaks field declares that this package breaks another and + prevents installation of the breaking package unless the package + named in Breaks is deconfigured first. This field should not be + used until the dpkg in Debian stable supports it. +8.1, 8.2 +Clarify which files should go into a shared library package, into a + separate package, or into the -dev package. Suggest -tools instead + of -runtime for runtime support programs, since that naming is more + common in Debian. +9.5 +Files in /etc/cron.{hourly,daily,weekly,monthly} must be + configuration files (upgraded from should). Mention the hourly + directory. +11.8.6 +Packages providing /etc/X11/Xresources files need not + conflict with xbase (<< 3.3.2.3a-2), which is + long-obsolete. +12.1 +Manual pages in locale-specific directories should use either the + legacy encoding for that directory or UTF-8. Country names should + not be included in locale-specific manual page directories unless + indicating a significant difference in the language. All + characters in the manual page source should be representable in the + legacy encoding for a locale even if the man page is encoded in + UTF-8. +12.5 +The Apache 2.0 license is now in common-licenses and should be + referenced rather than quoted in debian/copyright. +12.5 +Packages in contrib and non-free should state in the copyright file + that the package is not part of Debian GNU/Linux and briefly + explain why. +debconf +Underscore (_) is allowed in debconf template names. +

+ + Version 3.7.3.0 +

+ +Released Dec 2007. + +

+5.6.12 +Package version numbers may contain tildes, which sort before + anything, even the end of a part. +10.4 +Scripts may assume that /bin/sh supports local (at a basic + level) and that its test builtin (if any) supports -a and -o binary + logical operators. +8.5 +The substitution variable ${binary:Version} should be used in place + of ${Source-Version} for dependencies between packages of the same + library. +menu policy +Substantial reorganization and renaming of sections in the Debian + menu structure. Packages with menu entries should be reviewed to + see if the menu section has been renamed or if one of the new + sections would be more appropriate. +5.6.1 +The Source field in a .changes file may contain a version number + in parentheses. +5.6.17 +The acceptable values for the Urgency field are low, medium, high, + critical, or emergency. +8.6 +The shlibs file now allows an optional type field, indicating the + type of package for which the line is valid. The only currently + supported type is udeb, used with packages for the Debian + Installer. +3.9.1 +Packages following the Debian Configuration management + specification must allow for translation of their messages by using + a gettext-based system such as po-debconf. +12.5 +GFDL 1.2, GPL 3, and LGPL 3 are now in common-licenses and should + be referenced rather than quoted in debian/copyright. +

+ + Version 3.7.2.2 +

+ +Released Oct 2006. + +

+6.1 Maintainer scripts must not be world writeable (up from a + should to a must) +

+ + Version 3.7.2.0 +

+ +Released Apr 2006. + +

+11.5 Revert the cgi-lib change. +

+ + Version 3.7.1.0 +

+ +Released Apr 2006. + +

+10.2 +It is now possible to create shared libraries without + relocatable code (using -fPIC) in certain exceptional cases, + provided some procedures are followed, and for creating static + libraries with relocatable code (again, using -fPIC). + Discussion on debian-devel@lists.debian.org, getting a rough + consensus, and documenting it in README.Debian constitute most + of the process. +11.8.7 +Packages should install any relevant files into the directories + /usr/include/X11/ and /usr/lib/X11/, but if + they do so, they must pre-depend on x11-common (>= 1:7.0.0) +

+ + Version 3.7.0.0 +

+ +Released Apr 2006. + +

+11.5 +Packages shipping web server CGI files are expected to install + them in /usr/lib/cgi-lib/ directories. This location change + perhaps should be documented in NEWS +11.5 +Web server packages should include a standard scriptAlias of + cgi-lib to /usr/lib/cgi-lib. +9.1.1 +The version of FHS mandated by policy has been upped to + 2.3. There should be no changes required for most packages, + though new top level directories /media, /srv, + etc. may be of interest. +5.1, 5.6.3 +All fields, apart from the Uploaders field, in the control file + are supposed to be a single logical line, which may be spread + over multiple physical lines (newline followed by space is + elided). However, any parser for the control file must allow + the Uploaders field to be spread over multiple physical lines + as well, to prepare for future changes. +10.4 +When scripts are installed into a directory in the system + PATH, the script name should not include an extension that + denotes the scripting language currently used to implement it. + +9.3.3.2 +packages that invoke initscripts now must use invoke-rc.d to do + so since it also pays attention to run levels and other local + constraints. +11.8.5.2, 11.8.7, etc +We no longer use /usr/X11R6, since we have + migrated away to using Xorg paths. This means, for one thing, fonts + live in /usr/share/fonts/X11/ now, and /usr/X11R6 + is gone. +

+ + Version 3.6.2.0 +

+ +Released 2005 + +

+ +Recommend. doc-base, and not menu, for registering package documentation. + +8.1 +Run time support programs should live in subdirectories of + /usr/lib/ or /usr/share, and preferably the shared + lib is named the same as the package name (to avoid name collisions). + +11.5 +It is recommended that HTTP servers provide an alias /images to + allow packages to share image files with the web server + +

+ + Version 3.6.1.0 +

+ +Released Aug 2003. + +

+3.10.1 +Prompting the user should be done using debconf. Non debconf + user prompts are now deprecated. +

+ + Version 3.6.0 +

+ +Released Jul 2003. + +

+ +Restructuring causing shifts in section numbers and bumping of + the minor version number: + +Many packaging manual appendices that were integrated into policy + sections are now empty, and replaced with links to the Policy. + In particular, the appendices that included the list of control + fields were updated (new fields like Closes, Changed-By were added) + and the list of fields for each of control, .changes and .dsc files + is now in Policy, and they're marked mandatory, recommended or + optional based on the current practice and the behavior of the + deb-building tool-chain. + +Elimination of needlessly deep section levels, primarily in the + chapter Debian Archive, from which two new chapters were split out, + Binary packages and Source packages. What remained was reordered + properly, that is, some sects became sects etc. + +Several sections that were redundant, crufty or simply not designed + with any sort of vision, were rearranged according to the formula that + everything should be either in the same place or properly interlinked. + Some things remained split up between different chapters when they + talked about different aspects of files: their content, their syntax, + and their placement in the file system. In particular, see the new + sections about changelog files. +menu policy +Added Games/Simulation and Apps/Education to menu + sub-policy +C.2.2 +Debian changelogs should be UTF-8 encoded. +10.2 +shared libraries must be linked against all libraries that they + use symbols from in the same way that binaries are. +7.6 +build-depends-indep need not be satisfied during clean + target. +

+ + Version 3.5.10 +

+ +Released May 2003. + +

+11.8.3 +packages providing the x-terminal-emulator virtual package + ought to ensure that they interpret the command line exactly + like xterm does. +11.8.4 +Window managers compliant with the Window Manager Specification + Project may add 40 points for ranking in the alternatives +

+ + Version 3.5.9.0 +

+ +Released Mar 2003. + +

+3.4.2 +The section describing the Description: package field once again has + full details of the long description format. +4.2 +Clarified that if a package has non-build-essential + build-dependencies, it should have them listed in the Build-Depends + and related fields (i.e. it's not merely optional). +9.3.2 +When asked to restart a service that isn't already running, + the init script should start the service. +12.6 +If the purpose of a package is to provide examples, then the + example files can be installed into /usr/share/doc/package + (rather than /usr/share/doc/package/examples). +

+ + Version 3.5.8.0 +

+ +Released Nov 2002. + +

+12.7 +It is no longer necessary to keep a log of changes to the upstream + sources in the copyright file. Instead, all such changes should be + documented in the changelog file. +7.6 +menu policy +A new Apps/Science menu section is available +debconf policy +debconf specification cleared up, various changes. +12.1 +It is no longer recommended to create symlinks from nonexistent + manual pages to undocumented(7). Missing manual pages for programs + are still a bug. +

+ + Version 3.5.7.0 +

+ +Released Aug 2002. + +

+ +Packages no longer have to ask permission to call MAKEDEV in + postinst, merely notifying the user ought to be enough. +2.2.4 +cryptographic software may now be included in the main + archive. +3.9 +task packages are no longer permitted; tasks are now created by a + special Tasks: field in the control file. +11.8.4 +window managers that support netwm can now add 20 points when + they add themselves as an alternative for + /usr/bin/x-window-manager +10.1 +The default compilation options have now changed, one should + provide debugging symbols in all cases, and optionally step + back optimization to -O0, depending on the DEB_BUILD_OPTIONS + environment variable. +7.6, 4.8 +Added mention of build-arch, build-indep, etc, in describing + the relationships with `Build-Depends', `Build-Conflicts', + `Build-Depends-Indep', and `Build-Conflicts-Indep'. May need to + review the new rules. +8 +Changed rules on how, and when, to invoke ldconfig in maintainer + scripts. Long rationale. +

+ +

+Added the last note in 3.5.6 upgrading checklist item regarding build +rules, please see below +

+ + Version 3.5.6.0 +

+ +Released Jul 2001. + +

+2.5 +Emacs and TeX are no longer mandated by policy to be priority + standard packages +11.5 +Programs that access docs need to do so via /usr/share/doc, + and not via /usr/doc/ as was the policy previously +12.3 +Putting documentation in /usr/doc versus + /usr/share/doc is now a ``serious'' policy violation. +11.5 +For web servers, one should not provide non-local access to the + /usr/share/doc hierarchy. If one can't provide access + controls for the http://localhost/doc/ directory, then it is preferred + that one ask permission to expose that information during the install. +7 +There are new rules for build-indep/build-arch targets and + there is a new Build-Depend-Indep semantic. +

+ + Version 3.5.5.0 +

+ +Released May 2001. + +

+12.1 +Manpages should not rely on header information to have + alternative manpage names available; it should only use + symlinks or .so pages to do this + + + Clarified note in 3.5.3.0 upgrading checklist regarding + examples and templates: this refers only to those examples used + by scripts; see section 10.7.3 for the whole story + + +Included a new section 10.9.1 describing the use of + dpkg-statoverride; this does not have the weight of policy + + +Clarify Standards-Version: you don't need to rebuild your + packages just to change the Standards-Version! + +10.2 +Plugins are no longer bound by all the rules of shared + libraries + +X Windows related things: + + 11.8.1 + Clarification of priority levels of X Window System related + packages + + 11.8.3 + Rules for defining x-terminal-emulator improved + 11.8.5 + X Font policy rewritten: you must read this if you provide + fonts for the X Window System + + 11.8.6 + Packages must not ship /usr/X11R6/lib/X11/app-defaults/ + + 11.8.7 + X-related packages should usually use the regular FHS + locations; imake-using packages are exempted from this + + 11.8.8 + OpenMotif linked binaries have the same rules as + OSF/Motif-linked ones + + +

+ + Version 3.5.4.0 +

Released Apr 2001. + +

+11.6 +The system-wide mail directory is now /var/mail, no longer + /var/spool/mail. Any packages accessing the mail spool should + access it via /var/mail and include a suitable Depends field; + details in + +11.9; perl-policy +The perl policy is now part of Debian policy + proper. Perl programs and modules should follow the current Perl + policy + +

+ + Version 3.5.3.0 +

Released Apr 2001 + +

+7.1 +Build-Depends arch syntax has been changed to be less + ambiguous. This should not affect any current packages + +10.7.3 +Examples and templates files for use by scripts should now live + in /usr/share/<package> or + /usr/lib/<package>, with symbolic links from + /usr/share/doc/<package>/examples as needed + +

+ + Version 3.5.2.0 + +

Released Feb 2001. + +

+11.8.6 +X app-defaults directory has moved from + /usr/X11R6/lib/X11/app-defaults to + /etc/X11/app-defaults + +

+ + Version 3.5.1.0 + +

Released Feb 2001. + +

+8.1 +dpkg-shlibdeps now uses objdump, so shared libraries have to be + run through dpkg-shlibdeps as well as executables + +

+ + Version 3.5.0.0 + +

Released Jan 2001. + +

+11.8.5 +Font packages for the X Window System must now declare a + dependency on xutils (>= 4.0.2) + +

+ + Version 3.2.1.1 + +

Released Jan 2001. + +

+9.3.2 +Daemon startup scripts in /etc/init.d/ should not contain + modifiable parameters; these should be moved to a file in + /etc/default/ + +12.3 +Files in /usr/share/doc must not be referenced by any + program. If such files are needed, they must be placed in + /usr/share/<package>/, and symbolic links + created as required in /usr/share/doc/<package>/ + + +Much of the packaging manual has now been imported into the + policy document + +

+ + Version 3.2.1.0 + +

Released Aug 00. + +

+11.8.1 +A package of priority standard or higher may provide two + binaries, one compiled with support for the X Window System, + and the other without + +

+ + Version 3.2.0.0 + +

Released Aug 00. + +

+10.1 +By default executables should not be built with the debugging + option -g. Instead, it is recommended to support building the + package with debugging information optionally. Details in + +12.8 +Policy for packages where the upstream uses HTML changelog + files has been expanded. In short, a plain text changelog file + should always be generated for the upstream changes + + +Please note that the new release of the X window system (3.2) + shall probably need sweeping changes in policy + + +Policy for packages providing the following X-based features + has been codified: + + 11.8.2 + X server (virtual package xserver) + 11.8.3 + X terminal emulator (virtual package x-terminal-emulator) + 11.8.4 + X window manager (virtual package x-window-manager, and + /usr/bin/x-window-manager alternative, with priority + calculation guidelines) + + 12.8.5 + X fonts (this section has been written from scratch) + 11.8.6 + X application defaults + + +11.8.7 +Policy for packages using the X Window System and FHS issues + has been clarified; + +11.7.3 +No package may contain or make hard links to conffiles +8 +Noted that newer dpkg versions do not require extreme care in + always creating the shared lib before the symlink, so the unpack + order be correct + +

+ + Version 3.1.1.0 + +

Released Nov 1999. + +

+7.1 +Correction to semantics of architecture lists in Build-Depends + etc. Should not affect many packages + +

+ + Version 3.1.0.0 + +

Released Oct 1999. + +

+defunct +/usr/doc/<package> has to be a symlink pointing to + /usr/share/doc/<package>, to be maintained by postinst + and prerm scripts. + +7.1, 7.6 +Introduced source dependencies (Build-Depends, etc.) +9.3.4 +/etc/rc.boot has been deprecated in favour of + /etc/rcS.d. (Packages should not be touching this directory, + but should use update-rc.d instead) + +9.3.3 +update-rc.d is now the only allowable way of accessing the + /etc/rc?.d/[SK]??* links. Any scripts which manipulate them + directly must be changed to use update-rc.d instead. (This is + because the file-rc package handles this information in an + incompatible way.) + +12.7 +Architecture-specific examples go in + /usr/lib/<package>/examples + with symlinks from /usr/share/doc/<package>/examples/* + or from /usr/share/doc/<package>/examples itself + +9.1.1 +Updated FHS to a 2.1 draft; this reverts /var/state to + /var/lib + +9.7; mime-policy +Added MIME sub-policy document +12.4 +VISUAL is allowed as a (higher priority) alternative to EDITOR + +11.6 +Modified liblockfile description, which affects + mailbox-accessing programs. Please see the policy document for + details + +12.7 +If a package provides a changelog in HTML format, a text-only + version should also be included. (Such a version may be prepared + using lynx -dump -nolist.) + +3.2.1 +Description of how to handle version numbers based on dates + added + +

+ + Version 3.0.1.0 + +

Released Jul 1999. + +

+10.2 +Added the clarification that the .la files are essential for + the packages using libtool's libltdl library, in which case the .la + files must go in the run-time library package + +

+ + Version 3.0.0.0 + +

Released Jun 1999. + +

+9.1 +Debian formally moves from the FSSTND to the FHS. This is a + major change, and the implications of this move are probably + not all known. + +4.1 +Only 3 digits of the Standards version need be included in + control files, though all four digits are still permitted. + +12.6 +The location of the GPL has changed to + /usr/share/common-licenses. This may require changing the + copyright files to point to the correct location of the GPL and + other major licenses + +10.2 +Packages that use libtool to create shared libraries must + include the .la files in the -dev packages + +10.8 +Use logrotate to rotate log files + +now 11.8 +section 5.8 has been rewritten (Programs for the X Window + System) + +9.6; menu-policy +There is now an associated menu policy, in a separate document, + that carries the full weight of Debian policy + +11.3 +Programs which need to modify the files /var/run/utmp, + /var/log/wtmp and /var/log/lastlog must be + installed setgid utmp + +

+

+ Please note that section numbers below this point may not be up to date +

+ + Version 2.5.0.0 + +

Released Oct 1998. + +Policy Manual: +

+Rearranged the manual to create a new Section 4, Files + + Section 3.3 ("Files") was moved to Section 4. The Sections + that were Section 4 and Section 5 were moved down to become + Section 5 and Section 6. + + What was Section 5.5 ("Log files") is now a subsection of the + new Section 4 ("Files"), becoming section 4.8, placed after + "Configuration files", moving the Section 4.8 ("Permissions + and owners") to Section 4.9. All subsections of the old + Section 5 after 5.5 were moved down to fill in the number + gap. + + +Modified the section about changelog files to accommodate + upstream changelogs which were formatted as HTML. These + upstream changelog files should now be accessible as + /usr/doc/package/changelog.html.gz + +Symlinks are permissible to link the real, or upstream, + changelog name to the Debian mandated name. + +Clarified that HTML documentation should be present in some + package, though not necessarily the main binary package. + +Corrected all references to the location of the copyright + files. The correct location is /usr/doc/package/copyright + +Ratified the architecture specification strings to cater to the + HURD. + +

+ + Version 2.4.1.0 + +

Released Apr 1998. +

+ Policy Manual: +

+Updated section 3.3.5 Symbolic links: + symbolic links within a toplevel directory should be relative, + symbolic links between toplevel directories should be absolute + (cf., Policy Weekly Issue#6, topic 2) + + +Updated section 4.9 Games: + manpages for games should be installed in /usr/man/man6 + (cf., Policy Weekly Issue#6, topic 3) + +

+ + Packaging Manual: +

+Updated prefix of chapter 12, Shared Libraries: + ldconfig must be called in the postinst script if the package + installs shared libraries + (cf., Policy Weekly Issue #6, fixes:bug#20515) + +

+ + Version 2.4.0.0 + +

Released Jan 1998 + +

+Updated section 3.3.4 Scripts: + + /bin/sh may be any POSIX compatible shell + scripts including bashisms have to specify /bin/bash + as interpreter + scripts which create files in world-writable directories + (e.g., in /tmp) should use tempfile or mktemp for creating + the directory + + +Updated section 3.3.5 Symbolic Links: + symbolic links referencing compressed files must have the same + file extension as the referenced file + + +Updated section 3.3.6 Device files: + /dev/tty* serial devices should be used instead of + /dev/cu* + + +Updated section 3.4.2 Writing the scripts in /etc/init.d: + + all /etc/init.d scripts have to provide the following + options: start, stop, restart, force-reload + the reload option is optional and must never stop and restart + the service + + +Updated section 3.5 Cron jobs: + cron jobs that need to be executed more often than daily should + be installed into /etc/cron.d + + +Updated section 3.7 Menus: + removed section about how to register HTML docs to `menu' + (the corresponding section in 4.4, Web servers and applications, + has been removed in policy 2.2.0.0 already, so this one was + obsolete) + + +New section 3.8 Keyboard configuration: + details about how the backspace and delete keys should be + handled + + +New section 3.9 Environment variables: + no program must depend on environment variables to get a + reasonable default configuration + + +New section 4.6 News system configuration: + /etc/news/organization and /etc/news/server + should be supported by all news servers and clients + + +Updated section 4.7 Programs for the X Window System: + + programs requiring a non-free Motif library should be provided + as foo-smotif and foo-dmotif package + + if lesstif works reliably for such program, it should be linked + against lesstif and not against a non-free Motif library + + + +Updated section 4.9 Games: + games for X Windows have to be installed in /usr/games, + just as non-X games + +

+ + Version 2.3.0.1, 2.3.0.0 + +

Released Sep 1997. + +

+new section `4.2 Daemons' including rules for + /etc/services, /etc/protocols, + /etc/rpc, and /etc/inetd.conf + + +updated section about `Configuration files': + packages may not touch other packages' configuration files + + +MUAs and MTAs have to use liblockfile +

+ + Version 2.2.0.0 + +

Released July 1997. + +

+added section 4.1 `Architecture specification strings': + use + <arch>-linux + where <arch> is one of the following: + i386, alpha, arm, m68k, powerpc, sparc. + + +detailed rules for /usr/local + +user ID's + +editor/pager policy + +cron jobs + +device files + +don't install shared libraries as executable + +app-defaults files may not be conffiles +

+ + Version 2.1.3.2, 2.1.3.1, 2.1.3.0 + +

Released Mar 1997. + +

+two programs with different functionality must not have the + same name + +"Webstandard 3.0" + +"Standard for Console Messages" + +Libraries should be compiled with `-D_REENTRANT' + +Libraries should be stripped with strip --strip-unneeded + +

+ + Version 2.1.2.2, 2.1.2.1, 2.1.2.0 + +

Released Nov 1996. + +

+Some changes WRT shared libraries +

+ + Version 2.1.1.0 + +

Released Sep 1996. + +

+No hard links in source packages + +Do not use dpkg-divert or update-alternatives +without consultation + +Shared libraries must be installed stripped +

+ + Version 2.1.0.0 + +

Released Aug 1996. + +

+ Upstream changelog must be installed too +

+
+
diff --git a/virtual-package-names-list.txt b/virtual-package-names-list.txt index d1beab8..9ba66e5 100644 --- a/virtual-package-names-list.txt +++ b/virtual-package-names-list.txt @@ -83,6 +83,7 @@ System other applications time-daemon anything that serves as a time daemon ups-monitor anything that is capable of controlling an UPS + cron-daemon Any cron daemon that correctly follows policy requirements Documentation ------------- @@ -315,3 +316,6 @@ Russ Allbery: Rename inetd-superserver to inet-superserver 2 Dec 2007 Added ttf-japanese-gothic Added ttf-japanese-mincho + +Manoj Srivastava: + 21 Nov 2009 (Re)Added cron-daemon