content/dev/voting.html

<HTML> <HEAD> <TITLE>Apache voting rules and guidelines</TITLE> </HEAD>  <BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#000080" ALINK="#FF0000" > <H1>This document is now obsolete. Please refer to <A HREF="guidelines.html">the Apache Project guidelines</A> for up-to-date info.</H1> <H1 ALIGN=CENTER> <IMG SRC="images/apache_logo.gif" ALT=""> Apache voting rules and guidelines </H1> This document defines the rules and guidelines for Apache Group members to follow when voting on patches, documentation, or other action items to be applied to the Apache HTTP Server. The objective here is to avoid unnecessary conflict over changes and continue to produce a quality system in a timely manner. Not all conflict can be avoided, but at least we can agree on the procedures for conflict to be resolved. Some abbreviations used below... <DL> <DT>mailing list</DT> <DD>The Apache developers' mailing list. Subscription to the list is by invitation only, and only subscribers can post directly to the list.</DD> <DT>CURRENT</DT> <DD>The most recent version of the source. Used as the base code into which new patches are to be merged.</DD> <DT>C_VERSION</DT> <DD>The version number of CURRENT.</DD> <DT>NEXT</DT> <DD>The next version of the source. The product of applying approved patches to CURRENT</DD> </DL> <HR SIZE=6> <H2><IMG SRC="images/apache_feather_bullet.gif" ALT="o "> Issues and Action Items</H2> Many issues will be encountered by the project, each resulting in zero or more proposed action items. All action items may be voted on, but not all of them will require a formal vote. Issues should be raised on the mailing list as soon as they are identified. Action items must be raised on the mailing list. <H3>Types of Action Items</H3> <DL> <DT>Code Changes</DT> <DD>Code changes require peer review and testing over a wide range of server platforms. Therefore, all code changes must pass through a formal "patch vote", as described <A HREF="#patchvote">below</A>. All those participating in a patch vote must be willing and able to test the patched system.</DD> <DT>Documentation Changes</DT> <DD>Documentation changes are only voted on after (or during) the change. The author of the changes must notify the mailing list, preferably in advance of the work to avoid duplicate efforts, of where the changes are being made. If the changes are to existing documents, the existing documents should not be replaced until at least 24 hours after notifying the list. Any group member may veto a change, but must then provide real assistance to the author in correcting the problem if it can be corrected, and must rescind the veto once the problem has been corrected (this may be assumed in good faith).</DD> <DT>Long Term Plans</DT> <DD>Long term plans are simply announcements that group members are working on particular issues related to the Apache software. These are not voted on, but group members who do not agree with a particular plan, or think an alternate plan would be better, are obligated to inform the group of their feelings. In general, it is always better to hear about alternate plans prior to spending time on less adequate solutions. </DL> <H2><IMG SRC="images/apache_feather_bullet.gif" ALT="o "> Casting Votes</H2> Anyone on the mailing list may vote on any issue. However, the act of voting carries certain obligations -- voting members are not only stating their opinion, they are agreeing to help do the work of the Apache Project. Each vote can be made in one of three flavors: <DL COMPACT> <DT>+1</DT> <DD> Yes, agree, or the action should be performed. On some issues, this vote must only be given after the voter has tested the action on their own system(s). </DD> <DT>±0</DT> <DD> Abstain, no opinion, or I am happy to let the other group members decide this issue. An abstention may have detrimental affects if too many people abstain. </DD> <DT>-1</DT> <DD> No, I veto this action. All vetos must include an explanation of why the veto is appropriate. A veto with no explanation is void. </DD> </DL> All votes must be sent to the mailing list. <H2><IMG SRC="images/apache_feather_bullet.gif" ALT="o "> <A NAME="patchvote">Formal Patch Votes</A></H2> As mentioned above, changes to the source code require peer review and adequate testing across many platforms. The formal patch vote rules are intended to ensure that this happens even when we are all in a hurry to see things fixed. However, also see the section on <A HREF="#lazy-voting" >lazy voting</A> mode. There are four distinct roles in the patch vote process, each of which may be shared by multiple group members: patch provider, vote coordinator, voter, and version builder. Patch providers include anyone that has an action item to propose. Unless it is infeasible to do so, source code changes must be proposed in the form of input to the patch command. Feasibility is defined by each voter and the version builder(s), who may veto an action item if the action requires effort beyond what they are expected to perform. <H3>Uploading an Action Item</H3> Action items (usually patches) are uploaded to hyperreal (apache.org) via FTP, either directly into the directory for patches to CURRENT (/httpd/patches/for_Apache_C_VERSION/), or into an incoming FTP directory for later transfer into the patch directory. Each filename should at least hint at the action objective and include reference to: <OL> <LI>(C_VERSION) the version number of CURRENT</LI> <LI>(ID) the unique action item numeric ID</LI> <LI>(p) the patch letter, if an alternate patchfile is proposed</LI> </OL> The syntax for filenames not containing patches is: <PRE> ID.description</PRE> e.g., <PRE> 01.Modula3_rewrite</PRE> if the action item is not (yet) in the form of a patch. The syntax for filenames containing patches is: <PRE> IDp.description.C_VERSION.patch</PRE> e.g., <PRE> 01.ScriptAliasKaboom.0.8.11.patch 01a.ScriptAliasKaboom.0.8.11.patch 01b.ScriptAliasKaboom.0.8.11.patch</PRE> The ID number should start at 01, and be incremented for each new action item uploaded. <H3>Action Item Format</H3> An action item should contain a list of header information (formatted like e-mail or HTTP headers): <DL> <DT>From:</DT> <DD>A list of patch authors and/or people who identified the problem. <DT>Subject:</DT> <DD>A description of the problem being addressed. <DT>Requires:</DT> <DD>A list of other patches that must be applied before this one. <DT>Affects:</DT> <DD>A list of source file names that this patch affects <DT>Changelog:</DT> <DD>A couple of lines for use in a future changelog, so that the patch (if accepted) can be recorded. <DT>Comments:</DT> <DD>Any additional comments about the problem. </DL> followed by an empty line and then the patch (if any). <H3>Patch Format</H3> The patch should be created by using <CODE>diff -u</CODE> on the CURRENT source and the modified source. E.g., <PRE> diff -u http_main.c.orig http_main.c</PRE> All patches necessary to address an action item must be concatenated within a single patchfile. The source files affected by the patchfile should be listed in an Affects header. The completed patchfile should produce no errors or prompts when the command, <PRE> patch -s < patchfile</PRE> is issued. If the patch produces errors or prompts, then it may be rejected by others. Problems with patches should be reported to the mailing list as soon as they are noticed. Dependencies between patches must be noted with a Requires line in the patchfile headers. <H3>Alternate Patches</H3> Once uploaded, changes to the contents of a patchfile are limited to the header information (i.e., everything other than the patch itself). For example, the Changelog entry can be changed, but not the output of the <CODE>diff</CODE> command(s). Should the patch itself need changing, a new patchfile should be created with a new patchletter after the ID. Anyone can upload a patch to address a single problem, so alternative patches can be offered for the same problem. The author of the patch is the only person allowed to (or give permission to) have an existing patch removed. Removal of a patch means removal of the patchfile. Each patchfile is voted on independently. New alternate patches must garner their own votes -- they do not automatically inherit the votes for patches they replace. Patches for CURRENT can be uploaded at any time before or during a voting session. <H3>The Voting Session</H3> A voting session can be initiated by anyone so long as a volunteer or volunteers can be found to: <UL> <LI>be the vote coordinator: collect the votes cast by group members</LI> <LI>be the version builder: apply approved patches to create the NEXT version of the system.</LI> </UL> The person or persons volunteering to perform these tasks agree on a timetable and announce it on the mailing list. The important part of the timetable is the vote deadline, which specifies when the votes will be tallied and the new version can be built. Unless it is an <A HREF="#emergency">emergency</A>, the initial deadline should be at least three days after the announcement. The vote deadline can be moved if, using the same voting rules as for patches, there are enough votes and no vetos. The current deadline cannot be voted on. Group members can vote and comment on the patches under consideration as often as they want. The final vote (if votes are changed) of a person is assumed to invalidate previous votes. Votes are cast as follows; <DL COMPACT> <DT>+1</DT> <DD> can be given to a patch if the person has, <OL> <LI>read the patch header to see what problem it addresses</LI> <LI>successfully patched it into CURRENT</LI> <LI>observed no bad side-effects resulting from the patch.</LI> </OL> </DD> <DT>-1</DT> <DD> is a veto on the patch. All vetos must come with an explanation of why the veto is appropriate. A veto with no explanation is void. </DD> </DL> No veto can be overruled. If you disagree with the veto, you should lobby the person who cast the veto. Voters intending to veto a patch should make their opinions known to the group immediately, so that the problem can be remedied prior to the vote deadline, if possible. <H3>Vote Collection</H3> Votes are tallied by the vote coordinator as soon as the final vote deadline has passed. The results of the vote are then posted to the mailing list. In order to be approved, an action item file must receive at least 3 positive votes and NO vetos. Late +1 votes can be ignored or accepted by the vote coordinator at his/her discretion. A late veto has no value: It can only be used to try to convince positive voters to rethink. If a positive voter changes to a veto, that veto is valid even though it is late. <H3>Release Build and Announcement</H3> After the vote coordinator gives the version builder the results, NEXT is created by applying the approved patches to CURRENT, making the changes called for by other approved (non-patch) action items, adding the approved action item descriptions to the changelog, and incrementing the version number. NEXT is then uploaded by the version builder to hyperreal and placed in the pre-release directory (/httpd/dist) in compressed and gzip'd tar files that name the new version number. The availability of the new version is then announced on the private mailing list. After the version announcement, accidental mistakes made by the builder can be rectified without a vote, but must be announced to the group. Unless stated otherwise at the start of the vote session, NEXT is assumed to be intended for public release. If an objection to the public release is put forward, a majority decision vote will determine whether or not the release is made public. Unlike the other votes, a minority opinion cannot stop a public release. If NEXT is to be released publically, everyone on the mailing list should make the effort to download it and try it out. NEXT should not be publically released until 24 hours after it has been created and announced to the group. If one of the patches used to create NEXT is subsequently found to cause a more serious problem than those it fixed, this problem should be reported to the group and any public release postponed until a majority decision on how to rectify the problem is obtained. <H3><A NAME="emergency">Emergency Patch Votes</A></H3> In the event of an emergency patch/vote session to fix a security problem, the group may need to bypass the normal operating procedures described above in order to get a fix in place prior to any public announcement of the problem. Any group member may announce an emergency on the mailing list and is encouraged to do so immediately if notified about a severe problem. Any group member may veto an emergency in order to force it through the normal procedures. Patches created to solve an emergency problem may be linked directly from the Apache home page as soon as the patch has been created and tested by its author. However, this link must be removed or changed if the original patch is vetoed. The availability of an emergency patch may be announced to the public after 24hours or three +1 votes are given for the patch, whichever comes first. <H2> <A NAME="lazy-voting"> Lazy-Voting Mode </A> </H2> At some times, such as early in the devlopment cycle, it may be desirable to operate in what has been called "lazy" voting mode. This is essentially identical to the <A HREF="#patchvote" >formal voting process</A>, except that "silence gives assent" -- if 48 hours pass without a veto, a quorum of "aye" votes is assumed even not officially collected. Formal and lazy voting environments may co-exist; some topics may require formal votes whilst others may not. Common sense should be exercised, and potentially highly-controversial patches shouldn't be submitted under the lazy rules. When a patch submitter expects to take advantage of lazy voting mode, it must be explicitly stated in the patch submission. <HR SIZE=6> <ADDRESS> Rob Hartill and Roy Fielding 3 September 1995 </ADDRESS> <ADDRESS> Modified 26 August 1997 by Ken Coar </ADDRESS> </BODY> </HTML>

content/dev/voting.html (331 lines of code) (raw):