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.
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 valuable contributors and demonstrate commitment to the project, obtain the right to vote and commit directly to the source repository.
Users are the people who use the products of the Project. People in this role are not 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.
When a user starts to contribute code or documentation patches, they become a developer.
Users or Developers (further: Contributors) who give frequent and valuable contributions to a subproject of the Project and demonstrate commitment, may be asked to become a "Committer" for that subproject. A Committer has write access to the source code repository and voting rights enabling them to affect the future of the subproject.
In order for a Contributor to become a Committer, another Committer can nominate that Contributor. Once a Contributor is nominated, the Committers for a subproject will vote. If there are at least 3 positive votes and no negative votes, the new Committer is asked to sign an Apache Contributor License Agreement (CLA) and is provided with an Apache username and account, 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.
At times, Committers may go inactive for a variety of reasons. One that has been inactive for a while may be listed as Emeritus Committer.
A list of our current Committers can be found in our Project Credits.
Any Committers who desires to participate can join the PMC mailing list to become a member of the PMC. This committee is the official managing body of the Apache Cocoon Project and is responsible for setting overall project direction. 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.
Most discussion happens in the open on the dev mailing list. Only issues which absolutely must be discussed in private, are held on the pmc list (such as some licensing issues).
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 are not moderated based on content, and anybody is more than welcome to join them. However, you must be subscribed to post to a list.
To reduce the bandwidth demands on everyone, mail should not contain attachments. Please consider using the project's issue tracker or provide a URL for retrieval.
To join the mailing lists, see our Mailing List page.
The Project lists fall into the following categories:
User lists are for users of a product to converse about such things as configuration and operating of the products of the Project.
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 "action" is.
The SCM list is where all Subversion (SVN) code commit messages are automatically sent. All committers are required to subscribe to this list so that they can stay aware of changes to the repository.
Furthermore, the Cocoon project makes use of several ASF-wide announcements lists to announce new releases.
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 "Minimum Threshold Meritocracy".
All decisions revolve around "action items". Most action items require a vote to be approved. Votes can either be by majority or by consensus.
Action items include the following:
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 obliged to inform the group of their feelings.
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 changes.
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.
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.
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 final.
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.
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 consensus.
The act of voting on an action item carries certain obligations. Voters are not only stating their opinion, they are also agreeing to help do the work.
Any Contributor or Committer ("member") may call for an 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 "[VOTE]", and a distinctive one-line summary corresponding to the action item for the vote.
Each vote on an action item can be made in one of four flavors:
| +1 | "The action should be performed, and I will help." |
| +0 | "Abstain," "I support the action but I can't help." |
| -0 | "Abstain," "I don't support the action but I can't help with an alternative." |
| -1 | "The action should not be performed and I am offering an explanation or alternative." |
Anyone may vote on any action item or related issue. Only votes cast by the subproject's Committers are considered "binding". All binding vetos must also contain an explanation of why the veto is appropriate. When needed, at least 3 binding +1 votes are required for action-item approval.
An action item may need one of two types of approval:
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.
Most action items are subject to lazy approval, and do not require the posting of a formal result.
However, any other majority item that receives any -1 reply (later rescinded or not) must be followed by a "[VOTE-RESULT]" message before the action item is considered approved. Likewise, any consensus item that receives any binding veto must post a "[VOTE-RESULT]" 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.
A Public Release is not considered approved until the Release Manager posts a followup message with the legend "[VOTE-RESULT]" summarizing the replies.
Proposals are not a formal action item; however, the message offering a proposal should contain a Subject beginning with "[PROPOSAL]". 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.
Most other messages posted to the Developer's List usually involve either short-term or long-term plans. Often, a long-term plan will be made in the form of a "[PROPOSAL]". If appropriate, the proposed change or feature may then be entered to the subproject's STATUS file or TODO list.
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 "flavors" are taken to mean
| +1 | "Yes," "Agree." |
| +0 | "Abstain," "No opinion." |
| -0 | "Abstain," "Unsure." |
| -1 | "No," "Disagree." |
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.
Accordingly, as a matter of Apache Cocoon policy, these principles are adopted:
The Project's codebase is maintained in shared information repositories using SVN on the svn.apache.org machine. Only Committers have write access to these repositories. Everyone has read access via anonymous SVN.
All Java Language source code in the repository should preferably be written in conformance to the "Code Conventions for the Java Programming Language as published by Sun. Use of tab character for indenting is prohibited.
All source code committed to the Project'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.
Each of the Project's active source code repositories contain a
file named STATUS, or status.xml 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.
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.
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.
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's platform before being committed. This includes XML code that is used to build documentation.
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.
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.
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.
The patch should be created by using the diff -u command from the original software file(s) to the modified software file(s). For example:
or
or (Win32):
You can use TortoiseSVN 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.
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.
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.
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.
Responsibilities of the PMC include:
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 "off-list" meetings.
Only a PMC member may call for a vote of the PMC or cast a binding vote on a PMC matter.
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.
Most PMC actions require a "super-majority vote", where at least 75% of the current PMC members must cast a positive vote for the action to be approved. When computation of 75% of the current membership does not produce a whole number, the result shall be rounded the nearest whole number (.5 and higher rounds up).
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.
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.
There is no term limit for PMC members. The list of current PMC members is to be maintained in the Apache Cocoon Project Credits. All PMC members should be active Committers to one or more Apache Cocoon subprojects (preferably more).
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.
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.
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.