|
Support
Ex-Jakarta
|
This is a working draft document.
It is being created from discussions on the Jakarta General mailing list.
In due course, this document will be submitted for approval
as an update to the existing guidelines.
For the current version of the actual document, see < http://jakarta.apache.org/site/guidelines.html >.
For additional background, see also < http://www.x180.net/Mutterings/Apache/rules.html >.
Please note that:
Text being omitted from the existing guidelines is rendered in strikethrough.
New text is rendered in marroon.
|
Project Guidelines
|
This document defines the guidelines of The Jakarta 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.
This is a living document. Changes can be made by a 3/4
vote of the Project
Management Committee
, after discussion on the General mailing list.
|
|
Roles & Responsibilities
|
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.
Users are the people who use the products of the Project. People in
this role aren'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.
When a user starts to contribute code or documentation patches, they
become a developer.
Contributors are the people who write code or documentation patches or
contribute positively to the project in other ways. A volunteer's
contribution is always recognized. In source code, all volunteers
who contribute to a source file may add their name to the list of
authors for that file.
Contributors who give frequent and valuable contributions to a
subproject of the Project can have their status promoted to that of
a "Committer" for that subproject. A Committer
has write access to the source code repository and gains voting
rights allowing them to affect the future of the subproject.
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.
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.
A list of our current Committers can be found in our Project Credits.
Committers who frequently participate with valuable contributions may
have their status promoted to that of a "Project Management
Committee Member". This committee is the official managing
body of the Jakarta Project and is responsible for setting overall
project direction. In order to become a Member, someone on
the PMC must nominate the Committer. The individual may then be
approved with a 3/4 majority of the PMC.
To view the Project Management Committee bylaws,
click here.
For more about the Jakarta PMC, see the Project Management Committee bylaws.
A list of our current PMC Members can be found in our Project Credits.
|
|
Communication
|
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.
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 retrieval.
To join the mailing lists, see our
Mailing List page.
The Project's list fall into the following categories:
|
|
Announcement Lists
|
Announcement lists are very low traffic designed to communicate
important information, such as final releases of a subproject's
code, to a wide audience.
|
|
User Lists
|
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
|
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.
|
|
Commit Lists
|
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.
|
|
Decision Making
|
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 consist of 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 obligated 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. Voting members 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 three 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."
|
Votes cast by the subproject's Committers are considered "binding". 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:
Consensus
approval
An action requiring consensus approval must receive at least
3 binding +1 votes and no binding
vetos.
Majority approval
An action requiring majority approval must receive
at least 3 binding +1 votes and more
+1 votes than -1 votes.
All other Except for a public release, all action items are considered to have lazy approval until somebody
votes -1, after at which point they are the action item is decided by either converted to a formal consensus or majority vote, depending on the type of action item.
Note: "Lazy" 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.
Any Developer member may vote on any issue or action item or related issue. However, the
only binding votes are those cast by a Committer. If the vote is
about a change to the source code or documentation and the primary
author is a Contributor and not a Committer, the primary author of what
is being changed may also cast a binding vote on that issue
. When voting on an action item, the subproject's Committers may also include the word "binding" 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.
- A +1 vote regarding product code
is only can only be made
binding if the voter has tested the action on their own system(s) equipment.
- A binding +1 vote on a public release means the subproject's Committer agrees to provide ongoing support for that release while it is current.
- An abstention may have detrimental effects if too many
people abstain.
- Vetos with no explanation are void.
No veto
can be overruled. 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.
- 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.
- 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.
-
Members who wish to discuss a vote before replying, may open another thread to help avoid premature vetos. Any +/-1's or +/-0's posted to an alternate thread, or any other thread not labeled "[VOTE]", are considered conversational, and do not qualify as an valid action-item vote. A "lazy item" remains subject to lazy approval until a valid -1 reply is
posted to the "[VOTE]" thread.
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 Jakarta policy, these principles are adopted:
-
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.
-
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.
-
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.
-
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.
|
|
Source Repositories
|
The Project's codebase is maintained in shared information
repositories using CVS on the dev.apache.org machine. Only
Committers have write access to these repositories. Everyone has
read access via anonymous CVS.
All Java Language source code in the repository must be written in
conformance to the "Code
Conventions for the Java Programming Language as published by Sun.
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 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.
The active status files are automatically posted to the Developer
mailing lists three times per week.
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.
A branch is considered "evolutionary" by lazy consensus. Upon any dispute (binding veto), a branch must be converted to "revolutionary"
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, "evolutionary" or "revolutionary", shall
meet the same standard for release approval.
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:
|
|
|
|
|
diff -u Main.java.orig Main.java >> patchfile.txt
|
|
|
|
|
|
or
|
|
|
|
|
|
cvs diff -u Main.java >> patchfile.txt
|
|
|
|
|
|
or (Win32)
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.
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.
|
|
Project Management Committee Bylaws
|
The Jakarta Project Management Committee (PMC) was formed by the Apache Board in September 1999. 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 Jakarta 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 Jakarta Project,
through its subprojects and products. Jakarta is a meritocracy, and decision making is delegated to the subproject Committers whenever possible.
This governing body is expected to
ensure the project's welfare and guide its overall direction. The PMC
may not necessarily participate in the day-to-day coding but is
involved in the overall development plans, the alleviation of any
bottlenecks, the resolution of conflicts, and the overall technical
success of the project.
Responsibilities of the PMC include:
-
the active discussion of Project issues, strategic direction, and forward progress,
-
the consideration and approval of new subprojects,
-
retiring inactive subprojects and Committers as necessary,
-
arbitrating otherwise intractable disputes regarding subproject voting and vetos,
-
the security and reliability of the Project's Web site, mailing lists, code repositories, and related services,
-
legal issues involving the Project and its subprojects, and
-
maintaining Project and subproject scope as chartered by the ASF corporation
The PMC shall conduct as much business as possible on the Jakarta General mailing list. Sensitive business may also be conducted on the closed PMC mailing list if prudent. The PMC may also convene regular
monthly 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 3/4's of the current PMC members must cast a positive vote for the action to be approved. When computation of 3/4'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).
The term of the PMC Chair is one year.
The election of the Chair may take place on the Jakarta General 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. T
he 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).
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.
|
|
About Jakarta
About Apache
Retired Subprojects
|
