fielding 98/01/25 01:08:34
Modified: . guidelines.html index.html Log: Completed draft of project guidelines. I would have added information about the role of release manager of a branch and how we decide when a release should be built, but I didn't want to start inventing policy until the stuff we already do is approved. Revision Changes Path 1.7 +150 -160 apache-devsite/guidelines.html Index: guidelines.html =================================================================== RCS file: /export/home/cvs/apache-devsite/guidelines.html,v retrieving revision 1.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- guidelines.html 1998/01/20 01:06:07 1.6 +++ guidelines.html 1998/01/25 09:08:33 1.7 @@ -13,13 +13,14 @@ <CENTER> <IMG SRC="images/apache_logo.gif" ALT=""> -<H1 ALIGN=CENTER>Apache Project Guidelines and Voting Rules</H1> +<H1 ALIGN=CENTER>Apache Project Guidelines</H1> <P><B>DRAFT</B>: These guidelines are not yet approved.</P> </CENTER> <P> -This document defines the rules and guidelines for the Apache Project. +This document defines the guidelines for the +<a href="http://dev.apache.org/">Apache Project</a>. It includes definitions of how conflict is resolved by voting, who is able to vote, and the procedures to follow for proposing and making changes to the Apache products. @@ -32,9 +33,9 @@ to be resolved. </P> -<P> -The following define some common terms: -</P> +<H2><IMG SRC="images/apache_feather_bullet.gif" ALT="o "> +People, Places, and Things</H2> + <DL> <DT><STRONG>Apache Group</STRONG></DT> <DD>The group of volunteers who are responsible for managing the @@ -42,7 +43,7 @@ products of the Apache Project, maintaining the Project's shared resources, speaking on behalf of the Apache Project, resolving license disputes regarding Apache products, and establishing - these rules and guidelines. + these guidelines. <P>Membership in the Apache Group is by invitation only and must be approved by consensus of the active Apache Group members. @@ -76,16 +77,15 @@ <DT><STRONG>CVS</STRONG></DT> <DD>All of the Apache products are maintained in shared information - repositories using <A HREF="devnotes.html">CVS on + repositories using <A HREF="devnotes">CVS on <EM>dev.apache.org</EM></A>. Only some of the Apache developers have write access to these repositories; everyone has read access via - <A HREF="anoncvs.txt">anonymous CVS</A>. Developers who want write + <A HREF="anoncvs">anonymous CVS</A>. Developers who want write access need to ask for it on the mailing list and, if approved, need to ask the admin of <EM>dev.apache.org</EM> for a user account.</DD> </DL> -<HR SIZE=6> <H2><IMG SRC="images/apache_feather_bullet.gif" ALT="o "> STATUS</H2> @@ -121,7 +121,7 @@ on that issue. All other votes are non-binding. All developers are encouraged to participate in decisions, but the decision itself is made by those who have been long-time contributors to the project. -In other words, the Apache Project is a meritocracy. +In other words, the Apache Project is a minimum-threshold meritocracy. </P> <P> @@ -160,12 +160,15 @@ </DL> <P> -An action item requiring <em>consensus</em> must receive +An action item requiring <em>consensus approval</em> must receive at least <STRONG>3 binding +1</STRONG> votes and <STRONG>no vetos</STRONG>. -An action item requiring <em>simple approval</em> must receive +An action item requiring <em>majority approval</em> must receive at least <STRONG>3 binding +1</STRONG> votes and more <STRONG>+1</STRONG> votes than <STRONG>-1</STRONG> votes (<EM>i.e.</EM>, a majority with a minimum -quorum of three positive votes). +quorum of three positive votes). All other action items are considered +to have <em>lazy approval</em> until someone votes <STRONG>-1</STRONG>, +after which point they are decided by either consensus or a majority vote, +depending upon the type of action item. </P> <P> @@ -178,38 +181,6 @@ Types of Action Items</H2> <DL> - <DT><STRONG>Release Testing</STRONG></DT> - <DT><STRONG>Release Plan</STRONG></DT> - <DT><STRONG>Showstoppers</STRONG></DT> - - <DT><STRONG>Code Changes</STRONG></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. <STRONG>However, see the section on - "<A HREF="#ctr">To Commit, or Not to Commit?</A>" - below, which modifies this paragraph.</STRONG></DD> - - <DT><STRONG>Documentation Changes</STRONG></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><STRONG>Short Term Plans</STRONG></DT> - <DD>Short term plans are announcements that a developer is working on - a particular set of documentation or code files, with the implication - that other developers should avoid them or try to coordinate their - changes. This is a good way to proactively avoid conflict and - possible duplication of work. - <DT><STRONG>Long Term Plans</STRONG></DT> <DD>Long term plans are simply announcements that group members are working on particular issues related to the Apache software. @@ -219,129 +190,148 @@ inform the group of their feelings. In general, it is always better to hear about alternate plans <strong>prior</strong> to spending time on less adequate solutions. + + <DT><STRONG>Short Term Plans</STRONG></DT> + <DD>Short term plans are announcements that a developer is working on + a particular set of documentation or code files, with the implication + that other developers should avoid them or try to coordinate their + changes. This is a good way to proactively avoid conflict and + possible duplication of work. + + <DT><STRONG>Release Plan</STRONG></DT> + <DD>A release plan is used to keep all the developers aware of when a + release is desired, who will be the release manager, when the + repository will be frozen in order to create the release, and + assorted other trivia to keep us from tripping over ourselves + during the final moments. Lazy majority decides each issue in + the release plan. + + <DT><STRONG>Release Testing</STRONG></DT> + <DD>After a new release is built, colloquially termed a tarball, it + must be tested before being released to the public. Majority + approval is required before the tarball can be publically released. + + <DT><STRONG>Showstoppers</STRONG></DT> + <DD>Showstoppers are issues that require a fix be in place + before the next public release. They are listed in the STATUS file + in order to focus special attention on the problem. An issue becomes + a showstopper when it is listed as such in STATUS and remains + so by lazy consensus. + + <DT><STRONG>Product Changes</STRONG></DT> + <DD>Changes to the Apache products, including code and documentation, + will appear as action items under several categories corresponding + to the change status: + <DL> + <DT><b>concept/plan</b> + <DD>An idea or plan for a change. These are usually only listed in + STATUS when the change is substantial, significantly impacts the + API, or is likely to be controversial. Votes are being requested + early so as to uncover conflicts before too much work is done. + <DT><b>proposed patch</b> + <DD>A specific set of changes to the current product in the form + of <a href="#patch">input to the patch command</a> (a diff output). + <DT><b>committed change</b> + <DD>A one-line summary of a change that has been committed to the + repository since the last public release. + </DL> + All product changes to the currently active repository are subject + to lazy consensus. All product changes to a prior-branch (old version) + repository require consensus before the change is committed. </DL> -<H2><A NAME="ctr"><IMG SRC="images/apache_feather_bullet.gif" ALT="o "> -To Commit, or Not to Commit?</A></H2> +<H2><IMG SRC="images/apache_feather_bullet.gif" ALT="o "> +When to Commit a Change</H2> + +<P> +Ideas must be review-then-commit; patches can be commit-then-review. +With a commit-then-review process, we trust that the developer doing the +commit has a high degree of confidence in the change. Doubtful changes, +new features, and large-scale overhauls need to be discussed before +being committed to a repository. Any change that affects the semantics +of arguments to configurable directives, significantly adds to the runtime +size of the program, or changes the semantics of an existing API function +must receive consensus approval on the mailing list before being committed. +</P> + +<P> +Each developer is responsible for notifying the mailing list and adding +an action item to STATUS when they have an idea for a new feature or +major change to propose for the product. The distributed nature of the +Apache project requires an advance notice of 48 hours in order to properly +review a major change -- consensus approval of either the concept or a +specific patch is required before the change can be committed. Note that +a member might veto the concept (with an adequate explanation), but later +rescind that veto if a specific patch satisfies their objections. +No advance notice is required to commit singular bug fixes. +</P> <P> -We are exploring a new process to help speed development, -"commit-then-review". With a commit-then-review process, we trust that -committers have a high degree of confidence in their committed patches ---- higher than the typical [PATCH] post to the mailing list. - -<UL> -<LI>Advance notice of ideas and features will be given. No advance notice - is required to do bug fixes. -<LI>The CVS tree should compile at all times. It's permitted to break - platforms (<EM>e.g.</EM>, Win32) if the probability is mentioned in - the commit log. -<LI>The committer is responsible for the quality of the third-party code - they bring into the code. -<LI>Related changes should be posted at once, or very closely together; - no half-committed projects in the code. - -<LI>Any changes: - <BR> - <UL> - <LI>which affect semantics of arguments to directives - <LI>which significantly add to the runtime size of the program - <LI>which change the semantics of existing API functions - </UL> - need to be discussed on the mailing list before it gets committed. - -<LI>A patch must be reversed if the equivalent of a "veto" comes from -another developer with commit access. - -</UL> - -<HR size="6">Remainder has not been re-edited yet. ...Roy - -<H3>Patch Format</H3> - -<P> -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. - -<P>The patch should be created by using <CODE>diff -u</CODE> on the -<STRONG>CURRENT</STRONG> source and the modified source. E.g.,</P> - -<PRE> diff -u http_main.c.orig http_main.c</PRE> - -<P>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.</P> +Related changes should be committed as a group, or very closely together. +Half-completed projects should not be committed unless doing so is +necessary to pass the baton to another developer who has agreed to +complete the project in short order. All code changes must be successfully +compiled on the developer's platform before being committed. +</P> + +<P> +The current source code tree should be capable of complete compilation +at all times. However, it is sometimes impossible for a developer on +one platform to avoid breaking some other platform when a change is +committed, particularly when completing the change requires access to +a special development tool on that other platform. If it is anticipated +that a given change will break some other platform, the committer must +indicate that in the commit log. +</P> + +<P> +The committer is responsible for the quality of any third-party code +or documentation they commit to the repository. All software committed +to the repository must be covered by the Apache LICENSE or contain a +copyright and license that allows redistribution under the same conditions +as the Apache LICENSE. +</P> + +<P> +A committed change must be reversed if it is vetoed by one of the voting +members and the veto conditions cannot be immediately satisfied by the +equivalent of a "bug fix" commit. The veto must be rescinded before the +change can be included in any public release. +</P> + +<H2><IMG SRC="images/apache_feather_bullet.gif" ALT="o "> +<a name="patch">Patch Format</a></H2> + +<P> +When a specific change to the software is proposed for discussion or +voting on the mailing list, it should be presented in +the form of input to the patch command. When sent to the mailing list, +the message should contain a Subject beginning with +<CODE>[PATCH]</CODE> and a distinctive one-line summary +corresponding to the action item for that patch. Afterwords, the patch +summary in the STATUS file should be updated to point to the Message-ID +of that message. + +<P> +The patch should be created by using the <CODE>diff -u</CODE> command +from the original software file(s) to the modified software file(s). +E.g.,</P> + +<PRE> diff -u http_main.c.orig http_main.c >> patchfile.txt</PRE> +or +<PRE> cvs diff -u http_main.c >> patchfile.txt</PRE> + +<P> +All patches necessary to address an action item should be concatenated +within a single patch message. If later modification of the patch +proves necessary, the entire new patch should be posted and not just +the difference between two patches. The STATUS file entry should then +be updated to point to the new patch message. <P>The completed patchfile should produce no errors or prompts when the command,</P> <PRE> patch -s < patchfile</PRE> -is issued. - -<P>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.</P> - -<H3>Alternate Patches</H3> - -<P>Once uploaded, changes to the contents of a patchfile are limited -to the header information (<EM>i.e.</EM>, 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). - -<P>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.</P> - -<P>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.</P> - -<P>Patches for <STRONG>CURRENT</STRONG> can be uploaded at any time before or -during a voting session.</P> - -<H3>Release Build and Announcement</H3> - -<P>Unless stated otherwise at the start of the vote session, all releases -are 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.</P> - -<P>If it is to be released publicly, everyone on the mailing -list should make the effort to download it and try it out. -should not be publically released until 24 hours after it has been created -and announced to the group.</P> - -<P>If one of the patches used to create <STRONG>NEXT</STRONG> 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.</P> - -<H3><A name="emergency">Emergency Patch Votes</A></H3> - -<P>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.</P> - -<P>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.</P> - -<P>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.</P> +is issued in the target repository. </BODY> </HTML> 1.15 +14 -18 apache-devsite/index.html Index: index.html =================================================================== RCS file: /export/home/cvs/apache-devsite/index.html,v retrieving revision 1.14 retrieving revision 1.15 diff -u -r1.14 -r1.15 --- index.html 1998/01/12 21:02:53 1.14 +++ index.html 1998/01/25 09:08:33 1.15 @@ -14,8 +14,8 @@ <!--#include virtual="header.html" --> <H1 ALIGN="CENTER"><SAMP>Dev.Apache.Org</SAMP> - Developer Resources</H1> <P> - This site includes many of the reference materials used by The Apache - Group in their development efforts. + This site includes many of the reference materials used by the Apache + Project. </P> <BLOCKQUOTE> Note that a lot of these documents may not be entirely up-to-date. @@ -23,6 +23,12 @@ be waiting for someone to get around to updating them. </BLOCKQUOTE> <UL TYPE="SQUARE"> + <LI><A HREF="guidelines">Apache Project Guidelines</A>, currently in + draft form. <A HREF="voting" >Old Guidelines</A>. + </LI> + <LI><A HREF="devnotes">Apache Development Notes</a> about + using CVS and maintaining the Apache site. + </LI> <LI><A HREF="http://bugs.apache.org/">Read-only</A>, or <A HREF="http://bugs.apache.org/private/">read-write</A> access to the bug database. (Read-write access requires authorisation.) @@ -38,11 +44,6 @@ >Apache project plan</A> (last modified on <!--#flastmod virtual="project-plan.html" -->) </LI> - <LI>Rules and information about - <A - HREF="voting" - >voting</A> - </LI> <LI>The Apache coding <A HREF="styleguide" @@ -55,18 +56,18 @@ >the API</A> (last modified on <!--#flastmod virtual="API.html" -->) </LI> - <LI>How to - <A - HREF="binaries" - >build binary distributions</A> - (last modified on <!--#flastmod virtual="binaries.html" -->) - </LI> <LI>Instructions for <A HREF="how-to-release" >rolling the release tarballs</A> (last modified on <!--#flastmod virtual="how-to-release.html" -->) </LI> + <LI>How to + <A + HREF="binaries" + >build binary distributions</A> + (last modified on <!--#flastmod virtual="binaries.html" -->) + </LI> <LI>A <a href="binbuild.sh">shell script to build a binary release</a>. </LI> <LI>Record of changes to the @@ -74,11 +75,6 @@ HREF="mmn" >module magic number</A> (last modified on <!--#flastmod virtual="mmn.txt" -->) - </LI> - <LI>Random notes about - <A - HREF="devnotes.html" - >using CVS and maintaining the Apache site</A> </LI> <LI>The <A