jvanzyl 2003/02/03 17:23:27
Added: xdocs communication.xml decisions.xml guidelines.xml
management.xml newproject.xml roles.xml source.xml
Log:
o Straight rip off of the Jakarta site with the appropriate substitutions.
I'll get something up as fast as I can and then the edits can begin
as required or desired.
Revision Changes Path
1.1 db-site/xdocs/communication.xml
Index: communication.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
<title>Communication</title>
</properties>
<body>
<section name="Communication">
<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 retrieval.
</p>
<p>
To join the mailing lists, see our
<a href="./mail.html">
Mailing List</a> page.
</p>
<p>
The Project's list fall into the following categories:
</p>
</section>
<section name="Announcement Lists">
<p>
Announcement lists are very low traffic designed to communicate
important information, such as final releases of a subproject's
code, to a wide audience.
</p>
</section>
<section name="User Lists">
<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>
</section>
<section name="Developer Lists">
<p>
Developer lists are for the developers of 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.
</p>
</section>
<section name="Commit Lists">
<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>
</section>
</body>
</document>
1.1 db-site/xdocs/decisions.xml
Index: decisions.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
<title>The DB Project</title>
</properties>
<body>
<section name="Decision Making">
<p>
All
<a href="./roles.html">Contributors</a> are encouraged
to participate in decisions, but the decision itself is made by
those that have
<a href="./roles.html">Committer</a>
status in the Project. In other words, the Project is a
"
<em>Minimum Threshold Meritocracy</em>".
</p>
<p>
Any subscriber to the list may vote on any issue or
action item. 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 uthor is a Contributor and not a
Committer, the primary author of whatis being changed may also
cast a binding vote on that issue.
</p>
<p>
The act of voting carries certain obligations. Voting members are
not only stating their opinion, they are also agreeing to help do
the work.
</p>
<p>Each vote can be made in one of three flavors:</p>
<table>
<tr>
<td>
<strong>+1</strong>
</td>
<td>
"Yes," "Agree," or "the action should be
performed." On some issues this is only binding if the voter
has tested the action on their own system(s).
</td>
</tr>
<tr>
<td>
<strong>+/-0</strong>
</td>
<td>
"Abstain," "no opinion". An abstention may
have detrimental effects if too many people abstain.
</td>
</tr>
<tr>
<td>
<strong>-1</strong>
</td>
<td>
"No." On issues where consensus is required, this vote
counts as a
<strong>veto</strong>. All vetos must contain an
explanation of why the veto is appropriate. 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.
</td>
</tr>
</table>
<p>
An action requiring consensus approval must receive at least
<strong>3 binding +1</strong> votes and
<strong>no binding
vetos</strong>. An action requiring majority approval must receive
at least
<strong>3 binding +1</strong> votes and more
<strong>+1</strong> votes than
<strong>-1</strong> votes. All other
action items are considered to have lazy approval until somebody
votes
<strong>-1</strong>, after which point they are decided by
either consensus or majority vote, depending on the type of action
item.
</p>
<h2>Action Items</h2>
<p>
All decisions revolve around "
<em>Action
Items.</em>" Action Items consist of the following:
</p>
<ul>
<li>Long Term Plans</li>
<li>Short Term Plans</li>
<li>Release Plan</li>
<li>Release Testing</li>
<li>Showstoppers</li>
<li>Product Changes</li>
</ul>
<h3>Long Term Plans</h3>
<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>
<h3>Short Term Plan</h3>
<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
changes.
</p>
<h3>Release Plan</h3>
<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.
</p>
<h3>Release Testing</h3>
<p>
After a new release is built, it must be tested before being
released to the public. Majority approval is required before the
release can be made.
</p>
<h3>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 these problems. An issue becomes a
showstopper when it is listed as such in the status file and remains
so by lazy consensus.
</p>
<h3>Product Changes</h3>
<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 consensus.
</p>
</section>
</body>
</document>
1.1 db-site/xdocs/guidelines.xml
Index: guidelines.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
<title>DB Project Guidelines</title>
</properties>
<body>
<section name="Project Guidelines">
<p>
This document defines the guidelines of The DB Project. 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 codebase of the
Project.
</p>
<ul>
<li>
<a href="./roles.html">Roles and Responsibilities</a>
<br/>
Defines the recognized roles in the project.
</li>
<li>
<a href="./communication.html">Communication</a>
<br/>
Defines how users and developers communicate.
</li>
<li>
<a href="./decisions.html">Decision Making</a>
<br/>
Defines how action items are proposed and voted on.
</li>
<li>
<a href="./source.html">Source Repositories</a>
<br/>
Defines how the Project's source code is organized
and developed.
</li>
<li>
<a href="./management.html">Project Management</a>
<br/>
Defines the roles and responsibilities of the
Project Management Committee (PMC).
</li>
<li>
<a href="./newproject.html">New Subproject Proposals</a>
<br/>
Defines the methodology for proposing new top level
DB Subprojects.
</li>
</ul>
<p>
This is a living document. Changes can be made by the Project
Management Committee. Suggestions for changes should be discussed
on the [EMAIL PROTECTED]
<a href="mail.html">mailing list</a>
</p>
</section>
</body>
</document>
1.1 db-site/xdocs/management.xml
Index: management.xml
===================================================================
<?xml version="1.0"?>
<document prefix="../site/" url="./management.xml">
<properties>
<author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
<title>Project Management Committee Bylaws</title>
</properties>
<body>
<section name="Project Management Committee Bylaws">
<p>
The Project Management Committee (PMC) was formed by the Apache Board
in September 1999. The number of PMC seats is set at seven.
Annually,
all seven seats will be up for renewal. The ASF board will be asked
to
provide a person or persons to administer the nominations and a
subsequent ballot. The administrator(s) will determine the mechanics
of
the voting procedures. Any committer to any DB code base will be
eligible to vote. Once the new PMC is in place, the first order of
business will be to determine a chairperson from amongst their ranks.
The list of current members can be found in our
<a href="../credits/whoweare.html"> Project Credits</a>.
</p>
<p>
<b>Roles</b>
<br/> The PMC is responsible for the strategic direction
and success of the DB Project. 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.
</p>
<p>
The PMC is answerable to the Apache Board with its Chairman serving as
primary liaison.
</p>
<p>
<b>Meetings</b>
<br/> The PMC
<a href="pmc/index.html">meets monthly</a>
with a majority of its members to discuss issues, determine strategic
direction, and forward progress. These meetings may take place online,
via teleconference, or via other means deemed effective by the PMC.
</p>
<p>
<b>Membership</b>
<br/> PMC members may resign at any time. The Chairman
may resign as Chairman at any time without resigning membership to the
PMC. The Chairman or any member may be removed from the PMC by a 3/4
vote of the PMC.
</p>
<p>
In the event that the number of members drops below 7, the remaining
PMC
members may choose to elect a new member to serve out the remainder of
the annual term. In order to be elected, a
person must have served as a
<a href="roles.html">Committer</a> and be
nominated by a PMC Member. Once nominated, all of the PMC will vote
and those receiving a 3/4 positive vote will become a member.
</p>
<p>
<b>Creation of subprojects</b>
<br/> 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 3/4 vote of the PMC.
</p>
</section>
</body>
</document>
1.1 db-site/xdocs/newproject.xml
Index: newproject.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
<author email="[EMAIL PROTECTED]">Ted Husted</author>
<title>New Project Proposals</title>
</properties>
<body>
<section name="Subproject Proposals">
<p>
Not every software product is suited for life at DB. Before proposing
a new subproject, it is important to read this document carefully and
determine
whether your product is a good fit.
</p>
</section>
<section name="Criteria">
<p>
Here are some best practices that we will expect to find in a
successful
proposal. This is not a checklist, but guidelines to help communicate
what
is expected of a DB subproject.
</p>
<p>
<strong>Meritocracy.</strong> Before submitting a proposal, be sure
to study
the guidelines that
<a href="guidelines.html">govern DB subprojects</a>.
These guidelines explain our system of Meritocracy, which is the core
of the DB Project. If the product developers do not wish to adopt
this system, then they should
<strong>not</strong> donate their code
to the Project, and should look elsewhere for hosting.
</p>
<p>
<strong>Community.</strong> DB is a Project of the
<a href="http://apache.org";>Apache Software Foundation</a>. A prime
purpose of
the ASF is to ensure that the Apache projects continue to exist
beyond the
participation of individual volunteers. Accordingly, a prime criteria
required
of any new subproject is that it already enjoys -- or has a high
potential for
attracting -- an active community of developers and users.
</p>
<p>
Proposals for non-established products have been accepted, most often
when
the proposal was tendered by experienced open source developers, who
understand
what it means to build a community.
</p>
<p>
A design document, developer and user documentation, example code,
and a
working implementation all help to increase the likelihood of
acceptance.
Well-documented products tend to build stronger communities than
products that rely source code and JavaDocs alone.
</p>
<p>
<strong>Core Developers.</strong> To considered, a product must have
at least 3 active developers who are already involved with the
codebase.
This is an absolute minimum, and it is helpful for there to more than
three developers. It is
<strong>very</strong> helpful for at least one of the
developers making the proposal to already be active in a DB
subproject or
other open source initiative.
</p>
<p>
At DB, the core developers of a product (the
<a href="roles.html">Committers</a>) manage the codebases and make the
day-to-day development decisions. We are only interested in products
that can guided by their own development communities. DB provides
the infrastructure, and some essential guidelines, but the Committers
must take responsibility for developing and releasing their own
product.
</p>
<p>
<strong>Alignment with existing Apache subprojects.</strong> Products
that
are already used by existing subprojects make attractive candidates,
since
bringing such a codebase into the Apache fold tends to benefit both
communities. Products with dependancies on existing Apache products
are also
attractive for the same reason.
</p>
<p>
<strong>Scope.</strong> DB products are generally server-side
software solutions written for the Java platform. Proposals for
products
outside this venue will have greater difficulty in being accepted.
</p>
</section>
<section name="Warning Signs">
<p>
These are anti-patterns that we have found detrimental to the success
of
a proposal. Some of these are lesson learned from the school of
hard-knocks, others are taken from proposals which have been rejected
in
the past. All will raise a red flag, making it unlikely that a
proposal
will be accepted.
</p>
<p>
<strong>Orphaned products.</strong> Products which have lost their
corporate sponsor (for whatever reason) do
<strong>not</strong> make good candidates.
These products will lack a development community and won't
have the support needed to succeed under the DB umbrella.
</p>
<p>
For example, we have seen proposals that contain paragraphs like this:
</p>
<source>
FooProduct is currently a production quality product, and in
fact is being used a live website. It was developed as a
product by FooCompany, with the intention that we would sell
it. However, due to various economic factors such as the
decline in FooProduct's intended market and the
recent difficulties in obtaining venture capital, we have
decided that at this time it is not feasible for us to
continue in that direction.
</source>
<p>
The alleged quality of a product is not the prime criteria. To be
accepted, we must believe that a product will attract volunteers to
extend and maintain it over the long term. A product like this,
arriving with no volunteer developers or open source community, does
not further
<a href="mission.html">DB's mission</a>, and would
not be accepted.
</p>
<p>
We generally recommend that an orphaned product start with an
independent host, and consider making a proposal after it has started
to build a community.
</p>
<p>
<strong>Inexperience with open source.</strong> We often receive
proposals that start with "We will open our software if you
choose to accept it." This is the wrong way to approach the proposal
process. A closed source project does not have an open community, and
so we have no way to tell if the developers can work in an open source
environment. Products that have lived on their own and have started
to develop their own community, have a much better chance of being
accepted.
</p>
<p>
If the product's developers have not worked with open source before,
it is recommended that they spend some time contributing to an
existing
open source project before trying to manage one of their own. Since
DB subprojects are managed by their own Committers, it is
important that a new product supported by people who understand
how open source works.
</p>
<p>
<strong>Homogenous developers.</strong> Apache communities attract
developers with diverse backgrounds. Products with a tightly-knit
team of developers may have difficulty shepherding new developers
into the fold. It is vital that we believe the developers will
discuss development issues openly with the community, and
<strong>not</strong> make decisions behind closed doors. We are
especially wary of products with developers who all share a
common employer or geographic location.
</p>
<p>
<strong>Reliance on salaried developers.</strong> DB has strong ties
to the business community. Many of our developers are encouraged by
their
employers to work open source projects as part of their regular job.
We feel that this is a Good Thing, and corporations should be
entitled to
contribute to open source, same as anyone else. However, we are wary
of
products which rely strongly on developers who only work on open
source
products when they are paid to do so. A product at DB must continue
to exist beyond the participation of individual volunteers. We
believe the
best indicator of success is when developers volunteer their own time
to
work open source projects.
</p>
<p>
<strong>No ties to other Apache products</strong>. Products
<strong>without</strong> a tie to any existing Apache product, and
that have
strong dependencies on alternatives to Apache products, do not make
good
candidates. Many Apache products are related through common licenses,
technologies, and through their volunteers. Products without
licensing,
technology, or volunteers in common will have trouble attracting a
strong community.
</p>
<p>
<strong>A fascination with the Apache brand.</strong> The
<a href="http://apache.org/LICENSE";>Apache Software License</a> is
quite
liberal and allows for the code to used in commercial products. This
can induce people to donate a commercial codebase to the ASF, allow it
developed as open source for a time, and then convert it back to
commercial use. While this would legal under the Apache Software
License, we are wary of proposals that seem to be more interested in
exposure than community.
</p>
</section>
<section name="Subproject Alternatives">
<p>
</p>
</section>
<section name="Who Decides">
<p>
Final acceptance is based the rules defined in the
<a
href="management.html">Project Management Committee Bylaws</a> which
state that "Creation of a new subproject requires approval by 3/4 vote
of the PMC." The proposal for a new subproject must submitted to the
DB General
<a href="mail.html">mailing list</a>, where the PMC
conducts business. All discussion regarding the proposal will occur
the General list, including the final vote.
</p>
</section>
</body>
</document>
1.1 db-site/xdocs/roles.xml
Index: roles.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
<author email="[EMAIL PROTECTED]">Ted Husted</author>
<title>Roles and Responsibilities</title>
</properties>
<body>
<section name="Roles & Responsibilities">
<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>
<h2>Users</h2>
<p>
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, 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 Contributor.
</p>
<h2>Contributors</h2>
<p>
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.
</p>
<h2>Committers</h2>
<p>
Contributors who give frequent and valuable contributions to a
subproject of the Project can have their status promoted to that of
a "
<em>Committer</em>" 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.
</p>
<p>
In order for a Contributor to become a Committer, another Committer
can nominate that Contributor or the Contributor can ask for it.
</p>
<p>
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. This is an
example offer letter that should be sent to the volunteer after
3 positive votes have been received:
</p>
<source><![CDATA[
Dear Contributor,
The DB project would like to offer you commit privileges.
We have been impressed with your contributions up till now, and
believe that your involvement will improve the quality of the
libraries we produce.
It is important that you realize that these commit privileges give
you access to the specific DB project repository for which you
are involved with. They do not provide commit access to any other
Apache based project. Those projects will have to grant you commit
privileges themselves.
If you are interested in having commit privileges, please just let us
know, and we will setup an account on apache.org. It would expedite
the process if you could provide your preferred account name and
possibly a public SSH key. This process could take a few days once
we get this information.
We all hope that you accept this invitation.
The DB Project Management Committee.
]]></source>
<p>
Once there are 3 positive votes and the response to the above letter
has been received, someone from the project community who already has
commit access should send email to:
<strong>root at apache.org</strong>
that the account should be created. The following information
must be included in the email:
</p>
<ul>
<li>
The name and email address of the new user.
(ie: John Smith <[EMAIL PROTECTED]>)
</li>
<li>
Suggested account userid. This is optional.
(ie: jmsith)
</li>
<li>
The project that the user should be given access to.
(ie: DB Foo)
</li>
<li>
The results of the votes. In other words, the names and email
addresses of the committers who approved the addition.
</li>
</ul>
<p>
The new committer should also send an email to
<strong>asf at jaguNET.com</strong>
with the following information (please cut and paste to return
format):
</p>
<blockquote>
Name: {your name}
<br/>
Email: {your email address on the ASF lists}
<br/>
Projects: {comma separated list of ASF projects to which you have
commit access}
<br/>
Key: {a blank line followed by your key}
</blockquote>
<p>For example:</p>
<blockquote>
Name: Joe Foobar
<br/>
Email: [EMAIL PROTECTED]
<br/>
Projects: Tomcat, httpd
<br/>
Key:
<br/>
adklajdAL()@ [EMAIL PROTECTED])U@()@@ @)U@
</blockquote>
<p>
Finally, a new committer should also submit a signed copy of the
Contributor
License Agreement to the ASF. See the
<a href="agreement.html">
<strong>Contributor
License Agreement page</strong>
</a> for details.
</p>
<p>
Note 0: If a committer already has an account on the apache.org server
and the committer needs commit access to additional projects, then all
that needs to be done is to have the user notify
[EMAIL PROTECTED] with the results of the voting (as documented
above) and the user will be given access. In other words, the root
email address should only be used on the basis of new account
creation.
</p>
<p>
Note 1: All committers will be given access to the db-site module
on request. In other words, committers should be able to update the
main DB website.
</p>
<!--
This may be required shortly. But not currently. jvz.
<p>
Note 2: If the module that the committer needs access to is a sub
module within a project (ie: jakarta-turbine-tdk or
jakarta-avalon-logkit), it is up to the individual project to
determine how to deal with giving out access. In other words, access
may be granted by default to all sub modules or it can be granted by
vote.
</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 their
status as a Committer. Getting access back is as simple as
re-requesting it on the project's Developer mailing list.
</p>
<p>
A list of some of our current Committers can be found in our
<a
href="./whoweare.html">Project Credits</a>.
</p>
<p>
<h2>Project Management Committee (PMC)</h2>
Committers who frequently participate with valuable contributions may
have their status promoted to that of a "
<em>Project Management
Committee Member</em>". This committee is the official managing
body of the DB 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.
</p>
<p>
To view the Project Management Committee bylaws,
<a href="management.html">
click here</a>.
</p>
<p>
A list of our current PMC Members can be found in our
<a
href="./whoweare.html">Project Credits</a>.
</p>
</section>
</body>
</document>
1.1 db-site/xdocs/source.xml
Index: source.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Jon S. Stevens</author>
<title>Source Repositories</title>
</properties>
<body>
<section name="Source Repositories">
<p>
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.
</p>
<p>
All Java Language source code in the repository must be written in
conformance to the "
<a
href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html";>Code
Conventions for the Java Programming Language</a> as published by
Sun, or in conformance with another well-defined convention specified
by the subproject. See the
<a href="faqs.html">FAQ page</a>
for links to subproject conventions.
</p>
<h2>License</h2>
<p>
All source code committed to the Project's repositories must be
covered by the
<a href="http://www.apache.org/foundation/licence-FAQ.html";>Apache
License</a>
or contain a copyright and license that allows redistribution under
the same
conditions as the Apache License.
</p>
<p>
Committers should update the copyright notice on the Apache License to
include the current year when they revise a source file. If it is
2002,
and you revise a source file from 1999, change the copyright notice in
the license to cite "1999, 2002". If the file was from 2001, we would
change it to 2001-2002. And so forth. This will happen most often in
the
early part of a year, but maintenance of the copyright date should
occur
year-round, as needed.
</p>
<p>
Any code, document, or binary that is committed to the Project's
repositories, but not being donated to the ASF, must be clearly
marked as
such. All contributors should have a
<a href="agreement.html">Contributor
License Agreement</a> on file.
</p>
<p>
Any
<a href="jars.html">JAR</a> committed to the Project's repositories
<strong>must</strong> be licensed for redistribution. BSD and MPL
style
licenses are generally fine, but many
<a href="jars.html">Sun JARs</a>
do not permit redistribution.
</p>
<h2>Status Files</h2>
<p>
Each of the Project's active source code repositories contain a file
named
<span class="code">STATUS</span> 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
developers are working on or want discussion about, and anything
else that may be useful to help the group track progress.
</p>
<p>
It is recommended that the active status files are automatically
posted to the developer mailing lists three times per week.
</p>
<h2>Branches</h2>
<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. All branches currently in use should
be documented by the respective projects. For example,
<a
href="/turbine/branches.html">Turbine</a> has page on the site that
details the branches currently in use.
</p>
<h2>Changes</h2>
<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 developer's platform before being
committed. Also, any unit tests should also pass.
</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 developer 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 "bug fix" commit. The
veto must be rescinded before the change can be included in any
public release.
</p>
<h2>Patches</h2>
<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
<span class="code">[PATCH]</span> and a distinctive one-line summary
in the subject corresponding to the action item for that patch.
</p>
<p>
The patch should be created by using the
<span class="code">diff
-u</span> command from the original software file(s) to the modified
software file(s). It is recommended that you submit patches against
the latest CVS versions of the software in order to avoid conflicts.
This will also ensure that you are not submitting a patch for a
problem
that has already been resolved.
</p>
<p>
For example:
</p>
<source>
diff -u Main.java.orig Main.java >> patchfile.txt
</source>
<p>or (preferred)</p>
<source>
cvs diff -u Main.java >> patchfile.txt
</source>
<p>or (Win32)</p>
<p>
You can use
<a href="http://www.wincvs.org/";>WinCVS</a> for a nice GUI or
you can install
<a href="http://sources.redhat.com/cygwin/";>Cygwin</a> 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
concatencated 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>
<p>
If your email client line wraps the patch, consider placing the patch
file up on a website and sending a message to the development list
with the URL so that the developers with commit access can download
the commit the patch file more easily. You can also add the patch as
part of a bug report.
</p>
<p>
When a patch has been checked into CVS, the person who checked in the
patch should send a message to the person who sent the patch in as
well as the mailing list specifying that the patch has been checked
in. The reason is that not everyone watches commit messages and it is
helpful for others to know what has been checked in and when in order
to help prevent people from applying the patch at the same time.
</p>
</section>
</body>
</document>
