policy/ap-process.rst

   1 Debian Policy changes process
   2 =============================
   3
   4 .. _process-introduction:
   5
   6 Introduction
   7 ------------
   8
   9 To introduce a change in the current Debian Policy, the change proposal
  10 has to go through a certain process.  [#]_
  11
  12 .. _process-change-goals:
  13
  14 Change Goals
  15 ------------
  16
  17 -  The change should be technically correct, and consistent with the
  18    rest of the policy document. This means no legislating the value of
  19    π. This also means that the proposed solution be known to work;
  20    iterative design processes do not belong in policy.
  21
  22 -  The change should not be too disruptive; if very many packages become
  23    instantly buggy, then instead there should be a transition plan.
  24    Exceptions should be rare (only if the current state is really
  25    untenable), and probably blessed by the TC.
  26
  27 -  The change has to be reviewed in depth, in the open, where any one
  28    may contribute; a publicly accessible, archived, open mailing list.
  29
  30 -  Proposal should be addressed in a timely fashion.
  31
  32 -  Any domain experts should be consulted, since not every policy
  33    mailing list subscriber is an expert on everything, including policy
  34    maintainers.
  35
  36 -  The goal is rough consensus on the change, which should not be hard
  37    if the matter is technical. Technical issues where there is no
  38    agreement should be referred to the TC; non-technical issues should
  39    be referred to the whole developer body, and perhaps general
  40    resolutions lie down that path.
  41
  42 -  Package maintainers whose packages may be impacted should have access
  43    to policy change proposals, even if they do not subscribe to policy
  44    mailing lists (policy gazette?).
  45
  46 .. _process-current:
  47
  48 Current Process
  49 ---------------
  50
  51 Each suggested change goes through different states. These states are
  52 denoted through either usertags of the debian-policy@packages.debian.org
  53 user or, for ``patch``, ``pending``, and ``wontfix``, regular tags.
  54
  55 `Current list of
  56 bugs <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done>`_
  57
  58 The Policy delegates are responsible for managing the tags on bugs and
  59 will update tags as new bugs are submitted or as activity happens on
  60 bugs. All Debian Developers should feel free to add the seconded tag as
  61 described below. Other tags should be changed with the coordination of
  62 the Policy Team.
  63
  64 .. _state-a-issue-raised:
  65
  66 State A: Issue raised
  67 ~~~~~~~~~~~~~~~~~~~~~
  68
  69 Detect need, like gaps/flaws in current policy, or a new rule should be
  70 added. Any user or developer may start this step. There is a decision
  71 point here; not all issues are in scope of policy.
  72
  73 `TAG: issue
  74 <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&tag=issue>`_
  75
  76 What needs to happen next: If this is in scope for Policy, discuss the
  77 issue and possible solutions, moving to the discussion tag, or if the
  78 matter is sufficiently clear, go directly to a proposal for how to
  79 address it, moving to the proposal tag. If this is not in scope for
  80 Policy, close the bug.
  81
  82 .. _state-b-discussion:
  83
  84 State B: Discussion
  85 ~~~~~~~~~~~~~~~~~~~
  86
  87 Discuss remedy. Alternate proposals. Discussion guided by delegates.
  88 There should be a clear time limit to this stage, but as yet we have not
  89 set one.
  90
  91 `TAG: discussion
  92 <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=discussion>`_
  93
  94 What needs to happen next: Reach a conclusion and consensus in the
  95 discussion and make a final proposal for what should be changed (if
  96 anything), moving to the proposal tag.
  97
  98 .. _state-c-proposal:
  99
 100 State C: Proposal
 101 ~~~~~~~~~~~~~~~~~
 102
 103 A final proposal has emerged from the discussion, and there is a rough
 104 consensus on how to proceed to resolve the issue.
 105
 106 `TAG: proposal
 107 <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=proposal>`_
 108
 109 What needs to happen next: Provided that the rough consensus persists,
 110 develop a patch against the current Policy document with specific
 111 wording of the change. Often this is done in conjunction with the
 112 proposal, in which case one may skip this step and move directly to
 113 patch tag.
 114
 115 .. _state-d-wording-proposed:
 116
 117 State D: Wording proposed
 118 ~~~~~~~~~~~~~~~~~~~~~~~~~
 119
 120 A patch against the Policy document reflecting the consensus has been
 121 created and is waiting for formal seconds. The standard patch tag is
 122 used for this state, since it's essentially equivalent to the standard
 123 meaning of that tag.
 124
 125 `TAG: patch
 126 <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=patch>`_
 127
 128 What needs to happen next: The proposal needs to be reviewed and
 129 seconded. Any Debian developer who agrees with the change and the
 130 conclusion of rough consensus from the discussion should say so in the
 131 bug log by seconding the proposal.
 132
 133 .. _state-e-seconded:
 134
 135 State E: Seconded
 136 ~~~~~~~~~~~~~~~~~
 137
 138 The proposal is signed off on by N Debian Developers. To start with,
 139 we're going with N=3, meaning that if three Debian Developers agree, not
 140 just with the proposal but with the conclusion that it reflects
 141 consensus and addresses the original issue -- it is considered eligible
 142 for inclusion in the next version of Policy. Since Policy is partly a
 143 technical project governance method, one must be a Debian Developer to
 144 formally second, although review and discussion is welcome from anyone.
 145 Once this tag has been applied, the bug is waiting for a Policy team
 146 member to apply the patch to the package repository.
 147
 148 `TAG: seconded
 149 <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=seconded>`_
 150
 151 What needs to happen next: A Policy maintainer does the final review and
 152 confirmation, and then applies the patch for the next Policy release.
 153
 154 This tag is not used very much because normally a Policy maintainer
 155 applies the patch and moves the proposal to the next state once enough
 156 seconds are reached.
 157
 158 .. _state-f-accepted:
 159
 160 State F: Accepted
 161 ~~~~~~~~~~~~~~~~~
 162
 163 Change accepted, will be in next upload. The standard pending tag is
 164 used for this state since it matches the regular meaning of pending.
 165
 166 `TAG: pending
 167 <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=pending>`_
 168
 169 What needs to happen next: The bug is now in the waiting queue for the
 170 next Policy release, and there's nothing left to do except for upload a
 171 new version of Policy.
 172
 173 .. _state-g-reject:
 174
 175 State G: Reject
 176 ~~~~~~~~~~~~~~~
 177
 178 Rejected proposals. The standard wontfix is used for this state.
 179 Normally, bugs in this state will not remain open; instead, a Policy
 180 team member will close them with an explanation. The submitter may then
 181 appeal to the tech-ctte if they so desire. Alternately, issues appealed
 182 to the tech-ctte may remain open with this tag while that appeal
 183 proceeds.
 184
 185 `TAG: wontfix
 186 <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=rejected>`_
 187
 188 We may use one of the following tags here, but to date we have only used
 189 dubious and ctte. It's not clear whether we need more tags for this
 190 stage.
 191
 192 **dubious**
 193     Not a policy matter
 194
 195 **ctte**
 196     Referred to the Technical Committee (tech-ctte)
 197
 198 **devel**
 199     Referred to the developer body
 200
 201 **delegate**
 202     Rejected by a Policy delegate
 203
 204 **obsolete**
 205     The proposal timed out without a conclusion
 206
 207 What needs to happen next: The bug should be closed once a final
 208 resolution is reached, or retagged to an appropriate state if that final
 209 resolution reverses the decision to reject the proposal.
 210
 211 .. _process-other-tags:
 212
 213 Other Tags
 214 ----------
 215
 216 All Policy bugs are additionally categorized by class of bug.
 217
 218 The normative tag is used for bugs that make normative changes to
 219 Policy, meaning that the dictates of Policy will change in some fashion
 220 as part of the resolution of the bug if the proposal is accepted. The
 221 full process is followed for such bugs.
 222
 223 `TAG: normative
 224 <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=normative>`_
 225
 226 The informative tag is used for bugs about wording issues, typos,
 227 informative footnotes, or other changes that do not affect the formal
 228 dictates of Policy, just the presentation. The same tags are used for
 229 these bugs for convenience, but the Policy maintainers may make
 230 informative changes without following the full process. Informative bugs
 231 fall under their discretion.
 232
 233 `TAG: informative
 234 <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=informative>`_
 235
 236 The packaging tag is used for bugs about the packaging and build process
 237 of the debian-policy Debian package. These bugs do not follow the normal
 238 process and will not have the other tags except for pending and wontfix
 239 (used with their normal meanings).
 240
 241 `TAG: packaging
 242 <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=debian-policy&pend-exc=done&tag=packaging>`_
 243
 244 .. [#]
 245    This process was originally developed by Margarita Manterola, Clint
 246    Adams, Russ Allbery and Manoj Srivastava.