Google Git
Sign in
apache / james-site / 7ba13f34459fe258fcf1488e31da7e58b5e91850 / . / content / guidelines.html
blob: 64ef3db860d2157685cfe0fd5dc6a0a49aae8542 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- Generated by Apache Maven Doxia at 2021-09-26 -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Apache James Project &#x2013; Apache James Project Guidelines</title>
<style type="text/css" media="all">
@import url("./css/james.css");
@import url("./css/maven-base.css");
@import url("./css/maven-theme.css");
@import url("./css/site.css");
@import url("./js/jquery/css/custom-theme/jquery-ui-1.8.5.custom.css");
@import url("./js/jquery/css/print.css");
@import url("./js/fancybox/jquery.fancybox-1.3.4.css");
</style>
<script type="text/javascript" src="./js/jquery/js/jquery-1.4.2.min.js"></script>
<script type="text/javascript" src="./js/jquery/js/jquery-ui-1.8.5.custom.min.js"></script>
<script type="text/javascript" src="./js/fancybox/jquery.fancybox-1.3.4.js"></script>
<link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
<meta name="author" content="James Project Web Team" />
<meta name="Date-Revision-yyyymmdd" content="20210926" />
<meta http-equiv="Content-Language" content="en" />
<!-- Google Analytics -->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-1384591-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script').item(0); s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body class="composite">
<div id="banner">
<a href="index.html" id="bannerLeft" title="james-logo.png">
<img src="images/logos/james-logo.png" alt="James Project" />
</a>
<a href="https://www.apache.org/index.html" id="bannerRight">
<img src="images/logos/asf_logo_small.png" alt="The Apache Software Foundation" />
</a>
<div class="clear">
<hr/>
</div>
</div>
<div id="breadcrumbs">
<div class="xleft">
<span id="publishDate">Last Published: 2021-09-26</span>
</div>
<div class="xright"> <a href="index.html" title="Home">Home</a>
|
<a href="documentation.html" title="James">James</a>
|
<a href="mime4j/index.html" title="Mime4J">Mime4J</a>
|
<a href="jsieve/index.html" title="jSieve">jSieve</a>
|
<a href="jspf/index.html" title="jSPF">jSPF</a>
|
<a href="jdkim/index.html" title="jDKIM">jDKIM</a>
</div>
<div class="clear">
<hr/>
</div>
</div>
<div id="leftColumn">
<div id="navcolumn">
<h5>James components</h5>
<ul>
<li class="expanded">
<a href="documentation.html" title="About James">About James</a>
<ul>
<li class="none">
<a href="mail.html" title="Mailing Lists">Mailing Lists</a>
</li>
<li class="none">
<a href="contribute.html" title="Contributing">Contributing</a>
</li>
<li class="none">
<strong>Guidelines</strong>
</li>
<li class="none">
<a href="https://issues.apache.org/jira/browse/JAMES" title="Issue tracker">Issue tracker</a>
</li>
<li class="none">
<a href="team-list.html" title="Who We Are">Who We Are</a>
</li>
<li class="none">
<a href="license.html" title="License">License</a>
</li>
<li class="none">
<a href="thanks.html" title="Thanks">Thanks</a>
</li>
<li class="none">
<a href="support.html" title="Professional support">Professional support</a>
</li>
<li class="none">
<a href="download.cgi" title="Download releases">Download releases</a>
</li>
</ul>
</li>
<li class="collapsed">
<a href="server/index.html" title="Server">Server</a>
</li>
<li class="collapsed">
<a href="mailet/index.html" title="Mailets">Mailets</a>
</li>
<li class="collapsed">
<a href="mailbox/index.html" title="Mailbox">Mailbox</a>
</li>
<li class="collapsed">
<a href="protocols/index.html" title="Protocols">Protocols</a>
</li>
<li class="collapsed">
<a href="mpt/index.html" title="MPT">MPT</a>
</li>
</ul>
<h5>Apache Software Foundation</h5>
<ul>
<li>
<strong>
<a title="ASF" href="http://www.apache.org/">ASF</a>
</strong>
</li>
<li>
<a title="Get Involved" href="http://www.apache.org/foundation/getinvolved.html">Get Involved</a>
</li>
<li>
<a title="FAQ" href="http://www.apache.org/foundation/faq.html">FAQ</a>
</li>
<li>
<a title="License" href="http://www.apache.org/licenses/" >License</a>
</li>
<li>
<a title="Sponsorship" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
</li>
<li>
<a title="Thanks" href="http://www.apache.org/foundation/thanks.html">Thanks</a>
</li>
<li>
<a title="Security" href="http://www.apache.org/security/">Security</a>
</li>
</ul>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
</a>
</div>
</div>
<div id="bodyColumn">
<div id="contentBox">
<section>
<h2><a name="Apache_James_Project_Guidelines"></a>Apache James Project Guidelines</h2>
<p>
This document defines the guidelines for the Apache James Project. 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 James products.
</p>
<p>
The objective here is to avoid unnecessary conflict over changes and
continue to produce a quality system in a timely manner. Not all
conflict can be avoided, but at least we can agree on the
procedures for conflict to be resolved.
</p>
</section>
<section>
<h2><a name="People.2C_Places.2C_and_Things"></a>People, Places, and Things</h2>
<section>
<h3><a name="Apache_James_Project_Management_Committee"></a>Apache James Project Management Committee</h3>
<p>
The group of volunteers who are responsible for managing the Apache
James Project. This includes deciding what is distributed as
products of the Apache James Project, maintaining the
Project's shared resources, speaking on behalf of the Project,
resolving license disputes regarding Apache James products,
nominating new PMC members or committers, and establishing
these guidelines.
</p>
<p>
Membership in the Apache James PMC is by invitation only and must be approved
by consensus of the active Apache James PMC members. A PMC
member is considered inactive by their own declaration or by
not contributing in any form to the project for over six
months. An inactive member can become active again by
reversing whichever condition made them inactive (i.e., by
reversing their earlier declaration or by once again
contributing toward the project's work). Membership can be
revoked by a unanimous vote of all the active PMC members
other than the member in question.
</p>
</section>
<section>
<h3><a name="Apache_James_Committers"></a>Apache James Committers</h3>
<p>
The group of volunteers who are responsible for the technical aspects
of the Apache James Project. This group has write access to
the appropriate source repositories and these volunteers may
cast non-binding votes on any technical discussion.
</p>
<p>
Membership as a Committer is by invitation only and must be approved by
consensus of the active Apache James PMC members. A Committer
is considered inactive by their own declaration or by not
contributing in any form to the project for over six months.
An inactive member can become active again by reversing
whichever condition made them inactive (i.e., by reversing
their earlier declaration or by once again contributing toward
the project's work). Membership can be revoked by a unanimous
vote of all the active PMC members (except the member in
question if they are a PMC member).
</p>
</section>
<section>
<h3><a name="Mailing_list"></a>Mailing list</h3>
<p>
The Apache committers' primary mailing list for discussion of issues
and changes related to the project
(server-dev@james.apache.org). Subscription to the list is
open, but only subscribers can post directly to the list.
</p>
</section>
<section>
<h3><a name="Private_list"></a>Private list</h3>
<p>
The Apache James Project's private mailing list for discussion of
issues that are inappropriate for public discussion, such as
legal, personal, or security issues prior to a published fix.
Subscription to the list is only open to Apache James PMC
members and Apache Software Foundation Members.
</p>
</section>
<section>
<h3><a name="GIT"></a>GIT</h3>
<p>
All of the Apache James products are maintained in shared information
repositories using GIT on git-wip-us.apache.org. The Apache
committers have write access to these repositories; everyone
has read access via anonymous GIT.
</p>
</section>
</section>
<section>
<h2><a name="Status"></a>Status</h2>
<p>
Each of the Apache Project's active source code repositories contain a
file called &quot;STATUS&quot; 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 committers are working on or want discussion about,
and anything else that might be useful to help the group track
progress. The active STATUS files are automatically posted to
the mailing list each week.
</p>
<p>
Many issues will be encountered by the project, each resulting in zero
or more proposed action items. Issues should be raised on the
mailing list as soon as they are identified. Action items must
be raised on the mailing list and added to the relevant STATUS
file. All action items may be voted on, but not all of them will
require a formal vote.
</p>
</section>
<section>
<h2><a name="Voting"></a>Voting</h2>
<p>
Any of the Apache James Committers may vote on any issue or action
item. However, the only binding votes are those cast by active
members of the Apache James PMC; if the vote is about a change
to source code or documentation, the primary author of what is
being changed may also cast a binding vote on that issue. All
other votes are non-binding. All committers 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 minimum-threshold
meritocracy.
</p>
<p>
The act of voting carries certain obligations -- voting members are not
only stating their opinion, they are agreeing to help do the
work of the Apache Project. Since we are all volunteers, members
often become inactive for periods of time in order to take care
of their &quot;real jobs&quot; or devote more time to other projects. It
is therefore unlikely that the entire group membership will vote
on every issue. To account for this, all voting decisions are
based on a minimum quorum.
</p>
<p>
Each vote can be made in one of three flavors:
</p>
<p>
<b>+1</b>
<br />
Yes, agree, or the action should be performed. On some issues,
this vote is only binding if the voter has tested the action on
their own system(s).
</p>
<p>
<b>+-0</b>
<br />
Abstain, no opinion, or I am happy to let the other group
members decide this issue. An abstention may have detrimental
effects if too many people abstain.
</p>
<p>
<b>-1</b>
<br />
No. On issues where consensus is required, this vote counts as a
veto. All vetos must include an explanation of why the veto is
appropriate. A veto with no explanation is 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.
</p>
<p>
An action item requiring consensus approval must receive at least 3
binding +1 votes and no vetos. An action item requiring majority
approval must receive at least 3 binding +1 votes and more +1
votes than -1 votes (i.e., a majority with a minimum quorum of
three positive votes). All other action items are considered to
have lazy approval until someone votes -1, after which point
they are decided by either consensus or a majority vote,
depending upon the type of action item.
</p>
<p>
Votes are tallied within the STATUS file, adjacent to the action item
under vote. All votes must be either sent to the mailing list or
added directly to the STATUS file entry for that action item.
</p>
<p>
Votes are to remain open for 72 hours after which the developer who put
forth the vote should tabulate the result and send this to the
mailing list. A developer should be sensitive to holidays that
could dampen participation in the vote.
</p>
</section>
<section>
<h2><a name="Types_of_Action_Items"></a>Types of Action Items</h2>
<section>
<h3><a name="Long_Term_Plans"></a>Long Term Plans</h3>
<p>
Long term plans are simply announcements that group members are working
on particular issues related to the Apache software. These are
not voted on, but group members who do not agree with a
particular plan, or think an alternate plan would be better,
are obligated to inform the group of their feelings. In
general, it is always better to hear about alternate plans
prior to spending time on less adequate solutions.
</p>
</section>
<section>
<h3><a name="Short_Term_Plans"></a>Short Term Plans</h3>
<p>
Short term plans are announcements that a developer is working on a
particular set of documentation or code files, with the
implication that other committers should avoid them or try to
coordinate their changes. This is a good way to proactively
avoid conflict and possible duplication of work.
</p>
</section>
<section>
<h3><a name="Release_Plan"></a>Release Plan</h3>
<p>
A release plan is used to keep all the committers 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.
</p>
</section>
<section>
<h3><a name="Release_Testing"></a>Release Testing</h3>
<p>
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.
</p>
</section>
<section>
<h3><a name="Showstoppers"></a>Showstoppers</h3>
<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 the problem. An issue becomes a
showstopper when it is listed as such in STATUS and remains so
by lazy consensus.
</p>
</section>
<section>
<h3><a name="Product_Changes"></a>Product Changes</h3>
<p>
Changes to the Apache James products, including code and documentation,
will appear as action items under several categories
corresponding to the change status:
</p>
</section>
<section>
<h3><a name="Concept.2FPlan"></a>Concept/Plan</h3>
<p>
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.
</p>
</section>
<section>
<h3><a name="Proposed_Patch"></a>Proposed Patch</h3>
<p>
A specific set of changes to the current product in the form of
input to the patch command (a diff output).
</p>
</section>
<section>
<h3><a name="Committed_Change"></a>Committed Change</h3>
<p>
A one-line summary of a change that has been committed to the
repository since the last public release.
</p>
<p>
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.
</p>
</section>
</section>
<section>
<h2><a name="When_to_Commit_a_Change"></a>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>
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 &quot;bug fix&quot; commit. The veto must
be rescinded before the change can be included in any public
release.
</p>
</section>
<section>
<h2><a name="Patch_Format"></a>Patch Format</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 [PATCH] 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>
<p>
The patch should be created by using the diff -u command from the
original software file(s) to the modified software file(s).
E.g.,
</p>
<div class="source">
<pre>
diff -u James.java.orig James.java &gt;&gt; patchfile.txt
</pre></div>
<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>
<p>
The completed patchfile should produce no errors or prompts when the
command,
</p>
<div class="source">
<pre>
patch -s &lt; patchfile
</pre></div>
<p>
is issued in the target repository.
</p>
</section>
</div>
</div>
<div class="clear">
<hr/>
</div>
<div id="footer">
<div class="xright">Copyright &#169; 2006-2021
<a href="https://www.apache.org/">The Apache Software Foundation</a>.
All Rights Reserved.
</div>
<div class="clear">
<hr/>
</div>
</div>
</body>
</html>