cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject cvs commit: cocoon-site/src/documentation/content/xdocs guidelines.xml site.xml
Date Tue, 29 Jul 2003 08:32:29 GMT
stevenn     2003/07/29 01:32:29

  Modified:    src/documentation/content/xdocs site.xml
  Added:       src/documentation/content/xdocs guidelines.xml
  draft Cocoon Project guidelines as a discussion starter - copied verbatim from Jakarta guidelines
  Revision  Changes    Path
  1.9       +1 -0      cocoon-site/src/documentation/content/xdocs/site.xml
  Index: site.xml
  RCS file: /home/cvs/cocoon-site/src/documentation/content/xdocs/site.xml,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- site.xml	3 Jul 2003 14:25:02 -0000	1.8
  +++ site.xml	29 Jul 2003 08:32:29 -0000	1.9
  @@ -4,6 +4,7 @@
     <about label="About Cocoon">
       <index label="Welcome" href="index.html"/>
       <whoweare label="Who we are" href="whoweare.html"/>
  +    <guidelines label="Draft guidelines" href="guidelines.html"/>
       <history label="History" href="history.html"/>
       <news label="News" href="news/">
         <overview label="Latest" href="index.html"/>
  1.1                  cocoon-site/src/documentation/content/xdocs/guidelines.xml
  Index: guidelines.xml
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN"
      <title>Cocoon Project Guidelines - DRAFT</title>
      <warning>DRAFT INITIAL VERSION - these guidelines have not been voted upon
      <p>This document defines the guidelines of the Apache Cocoon Project and
      its subprojects. It includes definitions of the various categories of
      membership, who is able to vote, how conflicts are resolved by voting, and
      the procedures to follow for proposing and making changes to the codebases
      of the Project. Each subproject may adopt additional guidelines, which may
      extend but not supercede the Project guidelines.</p>
        <title>Roles &#38; Responsibilities</title>
        <p>The roles and responsibilities that people can assume in the project
        are based on merit. Everybody can help no matter what their role. Those
        who have been long term or valuable contributors to the project obtain
        the right to vote and commit directly to the source repository.</p>
          <p>Users are the people who use the products of the Project. People in
          this role aren&#39;t contributing code, but they are using the
          products, reporting bugs, making feature requests, helping other
          users, extending the online FAQ, and such. This is by far the most
          important category of people as, without users, there is no reason for
          the Project.</p>
          <p>When a user starts to contribute code or documentation patches,
          they become a developer.</p>
          <p>Contributors are the people who write code or documentation patches
          or contribute positively to the project in other ways. A
          volunteer&#39;s contribution is always recognized. <code>In source
          code, all volunteers who contribute to a source file may add their
          name to the list of authors for that file.</code></p>
          <p>Contributors who give frequent and valuable contributions to a
          subproject of the Project can have their status promoted to that of a
          <em>&#34;Committer&#34;</em> for that subproject. A Committer
          write access to the source code repository and gains voting rights
          allowing them to affect the future of the subproject.</p>
          <p>In order for a Contributor to become a Committer, another Committer
          can nominate that Contributor or the Contributor can ask for it. Once
          a Contributor is nominated, all of the Committers for a subproject
          will vote. If there are at least 3 positive votes and no negative
          votes, the Contributor is converted into a Committer and given write
          access to the source code repository for that subproject. Before
          receiving write access, a Committer must also affirm that they have
          read and understood these guidelines, and agree to abide by their
          terms, as they may be revised from time to time.</p>
          <p>At times, Committers may go inactive for a variety of reasons. A
          Committer that has been inactive for 6 months or more may lose his or
          her status as a Committer.</p>
          <p><code>A list of our current Committers can be found in our Project
          <title>Project Management Committee (PMC)</title>
          <p>Committers who frequently participate with valuable contributions
          may have their status promoted to that of a <em>&#34;Project
          Management Committee Member&#34;</em>. This committee is the official
          managing body of the Apache Cocoon Project and is responsible for
          setting overall project direction. <code>For more about the Apache
          Cocoon PMC, see the Project Management Committee bylaws. A list of our
          current PMC Members can be found in our Project Credits.</code></p>
        <title>Communication </title>
        <p>The Project obtains its strength from the communication of its
        members. In order for members to easily communicate with each other, the
        Project has a variety of mailing lists. These lists, with the exception
        of the announcement lists, are not moderated and anybody is more than
        welcome to join them. However, you must be subscribed to post to a list.</p>
        <p>To reduce the bandwidth demands on everyone, mail should not contain
        attachments. It is recommended that you place interesting material (such
        as patches) either within the body of the message or provide a URL for
        <p>To join the mailing lists, see our Mailing List page.</p>
        <p>The Project&#39;s list fall into the following categories:</p>
          <title>Announcement Lists</title>
          <p>Announcement lists are very low traffic designed to communicate
          important information, such as final releases of a subproject&#39;s
          code, to a wide audience.</p>
          <title>User Lists</title>
          <p>User lists are for users of a product to converse about such things
          as configuration and operating of the products of the Project.</p>
          <title>Developer Lists</title>
          <p>Developer lists are for the contributors to the project. On these
          lists suggestions and comments for code changes are discussed and
          action items are raised and voted on. For the developer community,
          these lists are the very center of the project where all the
          &#34;action&#34; is.</p>
          <title>Commit Lists</title>
          <p>The commit lists are where all CVS code commit messages are sent.
          All committers are required to subscribe to this list so that they can
          stay aware of changes to the repository.</p>
        <title>Decision Making</title>
        <p>All Contributors are encouraged to participate in decisions, but the
        decision itself is made by those that have Committer status in the
        Project. In other words, the Project is a <em>&#34;Minimum Threshold
          <title>Action Items</title>
          <p>All decisions revolve around <em>&#34;action items&#34;</em>.
          action items require a vote to be approved. Votes can either be by
          majority or by consensus.</p>
          <p>Action items include the following:</p>
            <li>Long Term Plans - No vote required.</li>
            <li>Short Term Plans - No vote required.</li>
            <li>Release Plan - Lazy majority vote on each issue, or lazy
            consensus if issue involves a product change.</li>
            <li>Release Testing - No vote required, once Release Plan is
            <li>Public Release - Majority vote, if no showstoppers are listed in
            the status file.</li>
            <li>Showstoppers - Lazy consensus until resolved and removed from
            status file.</li>
            <li>Product Changes - Lazy consensus.</li>
          <title>Long Term Plans</title>
          <p>Long term plans are simply announcements that group members are
          working on particular issues related to the Project. These are not
          voted on, but Committers who do not agree with a particular plan, or
          think that an alternative plan would be better, are obligated to
          inform the group of their feelings.</p>
          <title>Short Term Plans</title>
          <p>Short term plans are announcements that a volunteer is working on a
          particular set of documentation or code files with the implication
          that other volunteers should avoid them or try to coordinate their
          <title>Release Plan</title>
          <p>A release plan is used to keep all volunteers aware of when a
          release is desired, who will be the Release Manager, when the
          repository will be frozen to create a release, and other assorted
          information to keep volunteers from tripping over each other. Lazy
          majority decides each issue in a release plan, or lazy consensus if
          the issue involves a product change.</p>
          <title>Release Testing</title>
          <p>After a new release is built, it must be tested before being
          released to the public. After the release plan is approved, the
          Release Manager will announce that a product is ready for testing.</p>
          <title>Public Release</title>
          <p>Once the Release Manager determines that testing is complete, and
          all showstoppers for the release have been resolved, the Release
          Manager shall call for a vote on the public release. Majority approval
          is required before the public release can be made. The Committers who
          approve a public release (vote +1) are expected to provide ongoing
          support for that release while it is current. The Release Manager must
          summarize the outcome of the vote before the public release becomes
          <p>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 these problems. An issue becomes a
          showstopper when it is listed as such in the status file and remains
          so by lazy consensus.</p>
          <title>Product Changes</title>
          <p>Changes to the products of the Project, including code and
          documentation, will appear as action items in the status file. All
          product changes to the currently active repository are subject to lazy
            <title>Action Item Votes</title>
            <p>The act of voting on an action item carries certain obligations.
            Voting members are not only stating their opinion, they are also
            agreeing to help do the work.</p>
            <p>Any Contributor or Committer (&#34;member&#34;) may call for
            action-item vote on the Developer mailing list. It is preferred that
            a vote be preceded by a formal proposal offered for discussion
            purposes. The message announcing a vote should contain a Subject
            beginning with &#34;[VOTE]&#34;, and a distinctive one-line summary
            corresponding to the action item for the vote.</p>
            <p>Each vote on an action item can be made in one of four flavors:</p>
                <td>&#34;The action should be performed, and I will help.&#34;</td>
                <td>&#34;Abstain,&#34; &#34;I support the action but I can&#39;t
                <td>&#34;Abstain,&#34; &#34;I don&#39;t support the
action but I
                can&#39;t help with an alternative.&#34;</td>
                <td>&#34;The action should not be performed and I am offering an
                explanation or alternative.&#34;</td>
            <p>Votes cast by the subproject&#39;s Committers are considered
            &#34;binding&#34;. When needed, at least 3 binding +1 votes are
            required for action-item approval.</p>
            <p>An action item may need one of two types of approval:</p>
              <li><strong>Consensus approval:</strong> An action requiring
              consensus approval must receive at least 3 binding +1 votes and no
              binding vetos.</li>
              <li><strong>Majority approval:</strong> An action requiring
              majority approval must receive at least 3 binding +1 votes and
              more +1 votes than -1 votes.</li>
            <p>Except for a public release, all action items are considered to
            have lazy approval until somebody votes -1, at which point the
            action item is converted to a formal consensus or majority vote,
            depending on the type of action item.</p>
            <note>&#34;Lazy&#34; means the action item has immediate tactic
            approval, and it is not necessary to tally the vote until a -1 reply
            is posted. Once a -1 reply is posted, the vote must be tallied and
            reported before the action item is considered approved. All
            action-item votes are lazy except for a public release vote.</note>
            <p>Any member may vote on any action item or related issue. When
            voting on an action item, the subproject&#39;s Committers may also
            include the word &#34;binding&#34; next to their vote, to simplify a
            tally if it is needed. All binding vetos must also contain an
            explanation of why the veto is appropriate.</p>
            <title>Voting Caveats</title>
              <li>A +1 vote regarding product code can only be made binding if
              the voter has tested the action on their own equipment.</li>
              <li>A binding +1 vote on a public release means the
              subproject&#39;s Committer agrees to provide ongoing support for
              that release while it is current.</li>
              <li>An abstention may have detrimental effects if too many people
              <li>Vetos with no explanation are void. If you disagree with the
              veto, you should lobby the person who cast the veto. Voters
              intending to veto an action item should make their opinions known
              to the group immediately so that the problem can be remedied as
              early as possible.</li>
              <li>If a Committer believes the explanation for a veto is invalid,
              an affirmation of the veto can be requested. If some other
              Committer does not affirm that the explanation for the veto is
              valid, the veto shall be void.</li>
              <li>If a dispute over a veto becomes intractable, the PMC may
              consent to arbitrate the matter, and, if appropriate, rescind the
              veto with a 3/4 majority vote of the PMC members.</li>
              <li>Members who wish to discuss a vote before replying, may open
              another thread to help avoid premature vetos. Any +/-1&#39;s or
              +/-0&#39;s posted to an alternate thread, or any other thread not
              labeled &#34;[VOTE]&#34;, are considered conversational, and do
              not qualify as an valid action-item vote. A &#34;lazy item&#34;
              remains subject to lazy approval until a valid -1 reply is posted
              to the &#34;[VOTE]&#34; thread.</li>
            <title>Vote Results</title>
            <p>Most action items are subject to lazy approval, and do not
            require the posting of a formal result.</p>
            <p>However, any other majority item that receives any -1 reply
            (later rescinded or not) must be followed by a
            &#34;[VOTE-RESULT]&#34; message before the action item is considered
            approved. Likewise, any consensus item that receives any binding
            veto must post a &#34;[VOTE-RESULT]&#34; message summarizing the
            result, and show that each veto was rescinded, before it is
            considered approved. In either case, the member who requested the
            vote should also post the result within 120 hours (5 days). Any
            question regarding the outcome of an action-item vote may be
            referred by a Committer to the PMC for arbitration.</p>
            <p>A Public Release is not considered approved until the Release
            Manager posts a followup message with the legend
            &#34;[VOTE-RESULT]&#34; summarizing the replies.</p>
            <title>Other Items</title>
            <p>Proposals are not a formal action item; however, the message
            offering a proposal should contain a Subject beginning with
            &#34;[PROPOSAL]&#34;. It is strongly recommended that a proposal be
            circulated before calling for a formal vote. Often, once members
            have had the chance to critique a proposal, an updated copy of a
            proposal can be reposted as the vote document.</p>
            <p>Most other messages posted to the Developer&#39;s List usually
            involve either short-term or long-term plans. Often, a long-term
            plan will be made in the form of a &#34;[PROPOSAL]&#34;. If
            appropriate, the proposed change or feature may then be entered to
            the subproject&#39;s STATUS file or TODO list.</p>
            <title>Voting on other matters</title>
            <p>There are other matters upon which members will vote that do not
            involve action items. The same general voting structure is used in
            these cases, except that the &#34;flavors&#34; are taken to mean</p>
                <td>&#34;Yes,&#34; &#34;Agree.&#34;</td>
                <td>&#34;Abstain,&#34; &#34;No opinion.&#34;</td>
                <td>&#34;Abstain,&#34; &#34;Unsure.&#34;</td>
                <td>&#34;No,&#34; &#34;Disagree.&#34;</td>
          <p>In any software development project there is a natural tension
          between revolution and evolution. Many software development teams,
          open or closed, have a team leader who can declare whether the code
          base is in evolutionary or revolutionary mode. In a volunteer
          meritocracy, this type of decision is difficult to make and impossible
          to enforce. Our meritocracy is fueled by voluntary contributions, and
          so we must allow everyone to contribute, and then base our final
          product decisions on the contributions we actually receive.</p>
          <p>Accordingly, as a matter of Apache Cocoon policy, these principles
          are adopted:</p>
            <li>Every committer has the right to revolution. Anyone can
            establish a branch or seperate whiteboard directory in which to
            experiment with new code seperate from the main trunk. The only
            responsibility a committer has when they do this is to announce
            their short and long range plans, and allow others who want to help
            to do so. Committers working on a revolutionary branch have the
            right to develop their approach free of interference.</li>
            <li>When a revolution is considered ready for prime time, the
            committer(s) shall propose a merge to the developers list. At that
            time, the overall community evaluates whether or not the code is
            ready to become part of, or to potentially replace, the trunk.
            Suggestions may be made, changes may be required. Once all issues
            have been taken care of and the merge is approved, the new code may
            become the trunk.</li>
            <li>All development branches should be unversioned. No branch,
            evolutionary or revolutionary, should have any official version
            standing. This allows several parallel tracks of development to
            occur with the final authority of what eventually becomes the trunk
            resting with the entire community of committers.</li>
            <li>The trunk is the official versioned line of the project. All
            evolutionary minded people are welcome to work on it to improve it.
            Evolutionary work is important and should not stop as it is always
            unclear when any particular revolution will be ready for prime time
            or whether it will be officially accepted.</li>
        <title>Source Repositories</title>
        <p>The Project&#39;s codebase is maintained in shared information
        repositories using CVS on the machine. Only Committers
        have write access to these repositories. Everyone has read access via
        anonymous CVS.</p>
        <p>All Java Language source code in the repository must be written in
        conformance to the &#34;Code Conventions for the Java Programming
        Language as published by Sun.</p>
          <p>All source code committed to the Project&#39;s repositories 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>
          <title>Status Files</title>
          <p>Each of the Project&#39;s active source code repositories contain a
          file named STATUS which is used to keep track of the agenda and plans
          for work within that repository. The status file includes information
          about release plans, a summary of code changes committed since the
          last release, a list of proposed changes that are under discussion,
          brief notes about items that individual volunteers are working on or
          want discussion about, and anything else that may be useful to help
          the group track progress.</p>
          <p>The active status files are automatically posted to the Developer
          mailing lists three times per week.</p>
          <p>Groups are allowed to create a branch for release cycles, etc. They
          are expected to merge completely back with the main branch as soon as
          their release cycle is complete.</p>
          <p>A branch is considered &#34;evolutionary&#34; by lazy consensus.
          Upon any dispute (binding veto), a branch must be converted to
          &#34;revolutionary&#34; status, and must be assigned a working name
          that does not imply it will be the next version of the product. Once a
          release plan for the branch has been approved, and the proposed
          release is ready for testing, it may be assigned a version name
          reflecting it is a product release candidate, and merged back with the
          main branch, as appropriate to the circumstances. Any branch,
          &#34;evolutionary&#34; or &#34;revolutionary&#34;, shall meet the
          standard for release approval. </p>
          <p>Simple patches to fix bugs can be committed then reviewed. With a
          commit-then-review process, the Committer is trusted to have a high
          degree of confidence in the change.</p>
          <p>Doubtful changes, new features, and large scale overhauls need to
          be discussed before committing them into the repository. Any change
          that affects the semantics of an existing API function, the size of
          the program, configuration data formats, or other major areas must
          receive consensus approval before being committed.</p>
          <p>Related changes should be committed as a group, or very closely
          together. Half complete projects should never be committed to the main
          branch of a development repository. All code changes must be
          successfully compiled on the contributor&#39;s platform before being
          committed. This includes XML code that is used to build documentation.</p>
          <p>The current source code tree for a subproject should be capable of
          complete compilation at all times. However, it is sometimes impossible
          for a contributor on one platform to avoid breaking some other
          platform when a change is committed. If it is anticipated that a given
          change will break the build on some other platform, the committer must
          indicate that in the commit message.</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 &#34;bug fix&#34; commit. The veto must be
          rescinded before the change can be included in any public release.</p>
          <p>When a specific change to a product is proposed for discussion or
          voting on the appropriate development 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
          [PATCH] and a distinctive one-line summary corresponding to the action
          item for that patch.</p>
          <p>The patch should be created by using the diff -u command from the
          original software file(s) to the modified software file(s). For
          <source>diff -u &#62;&#62; patchfile.txt</source>
          <source>cvs diff -u &#62;&#62; patchfile.txt</source>
          <p>or (Win32):</p>
          <p>You can use WinCVS for a nice GUI or you can install Cygwin which
          will enable you to use the bash shell and also installs a lot of other
          utilities (such as diff and patch) that will turn your PC into a
          virtual Unix machine.</p>
          <p>All patches necessary to address an action item should be
          concatenated within a single patch message. If later modification to
          the patch proves necessary, the entire new patch should be posted and
          not just the difference between the two patches. </p>
        <title>Project Management Committee Bylaws</title>
          <p>The Apache Cocoon Project Management Committee (PMC) was formed by
          the Apache Board in late 2002. The PMC is answerable to the Apache
          Board with its Chair serving as primary liaison. The Apache Software
          Foundation (ASF) owns the entire body of the Apache Public Licensed
          code, but delegates the daily maintenance of these codebases to
          individual Project Management Committees, including the Apache Cocoon
          PMC. The ASF is run as a meritocracy, with decision making delegated
          to the PMCs and their subproject Committers whenever possible.</p>
          <p>The PMC is responsible for the strategic direction and overall
          success of the Apache Cocoon Project, through its subprojects and
          products. Apache Cocoon is a meritocracy, and decision making is
          delegated to the subproject Committers whenever possible.</p>
          <p>Responsibilities of the PMC include:</p>
            <li>the active discussion of Project issues, strategic direction,
            and forward progress,</li>
            <li>the consideration and approval of new subprojects,</li>
            <li>retiring inactive subprojects and Committers as necessary,</li>
            <li>arbitrating otherwise intractable disputes regarding subproject
            voting and vetos,</li>
            <li>the security and reliability of the Project&#39;s Web site,
            mailing lists, code repositories, and related services,</li>
            <li>legal issues involving the Project and its subprojects, and</li>
            <li>maintaining Project and subproject scope as chartered by the ASF
          <p>The PMC shall conduct as much business as possible on the Apache
          Cocoon Developers mailing list. Sensitive business may also be
          conducted on the closed PMC mailing list if prudent. The PMC may also
          convene regular meetings with a majority of its members attending.
          These meetings may take place online, via teleconference, or via other
          means deemed effective by the PMC. The PMC shall post a regular status
          report to General list, along with minutes of any &#34;off-list&#34;
          <p>Only a PMC member may call for a vote of the PMC or cast a binding
          vote on a PMC matter.</p>
          <p>The voting pool is based on the current PMC membership. All PMC
          members are expected to formally vote or abstain when a vote is
          called. PMC members who continually fail to vote or otherwise
          participate may lose their PMC status.</p>
          <p>Most PMC actions require a &#34;super-majority vote&#34;, where
          least 3/4&#39;s of the current PMC members must cast a positive vote
          for the action to be approved. When computation of 3/4&#39;s of the
          current membership does not produce a whole number, the result shall
          be rounded the nearest whole number (.5 and higher rounds up).</p>
          <p>The term of the PMC Chair is one year. The election of the Chair
          may take place on the Apache Cocoon Developers list or at another
          meeting with a majority of PMC members in attendance. The Chair is
          elected by a simple majority of PMC members. All PMC members are
          expected to vote or to formally abstain. If a tie vote cannot be
          otherwise resolved, there shall be a simple majority vote of the
          subproject Committers on the General mailing list.</p>
          <p>The Chair may resign as Chair at any time without resigning
          membership to the PMC. The Chair may be re-elected to a subsequent
          term. The exiting Chair retains PMC membership status.</p>
          <p>There is no term limit for PMC members. The list of current PMC
          members is to be maintained in the Jakarta Project Credits. All PMC
          members should be active Committers to one or more Jakarta subprojects
          (preferably more).</p>
          <p>PMC members may resign at any time. Any member may be removed from
          the PMC by a super-majority vote of the PMC members. The Chair serves
          at the pleasure of the ASF Board.</p>
          <title>New Members</title>
          <p>A subproject Committer may be nominated for the PMC by a current
          PMC member. Nominees should realize that participation in the PMC
          requires a regular and sustained commitment of their time, and is not
          to be taken lightly. A nominee becomes a PMC member by a successful
          super-majority vote.</p>
          <title>Creation of subprojects</title>
          <p>PMC members may propose the creation of new subprojects. Proposals
          are to contain the scope of the project, identify the initial source
          from which the project is to be populated, identify the mailing
          list(s) if any which are to be created, and identify the initial set
          of Committers. Creation of a new subproject requires approval by
          super-majority vote of the PMC. It is preferred but not required that
          at least one PMC member be a Committer to a new subproject.</p>

View raw message