commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [Jakarta Commons Wiki] New: JakartaCommonsEtiquette
Date Wed, 19 May 2004 21:27:54 GMT
   Date: 2004-05-19T14:27:54
   Editor: <>
   Wiki: Jakarta Commons Wiki
   Page: JakartaCommonsEtiquette

   Moved page from old wiki

New Page:

= Jakarta Commons Etiquette =

This page describes and attempts to explain some of the peculiarities of Jakarta Commons.
This is etiquette defined by the community rather than the formal rules (for those see http//
This page was created (after several requests for information) to satisfy developers and committers
rather than users. (But if anyone wants to add user ettiquette, that'd be cool :)

The wiki seemed like a good place where this could be informally developed by the community.
It might become a web page later (and then again, it might not).

The information contained in this page is unoffical advice rather than rules that have been
officially adopted by the Commons team. It was founded by observations of the goings on in
the commons from the subproject's creation till the present.


= The Sandbox =

The sandbox is a space provided by Jakarta for the development of experimental code by existing
committers. It is divided into components. 

Any Jakarta committer has the right ask for karma and have it granted. The right place to
ask is on the commons-dev mailing list.

Components cannot be released from the sandbox.

= Sandbox Etiquette =

Committers have karma for the whole sandbox. This means that a committer could alter any component.
But we're all grown ups (right?) and so we'll play nicely together (right?). The right thing
to do is to ask on the list or talk to the owners of the component (see the STATUS file) before
diving in. The owners may not be still subscribed to the commons-dev list and so you might
need to contact them directly.

A little patience and discussion in this will avoid flames later :)

= Sandbox Oversight =

Oversight for the sandbox is provided by the Commons team. Oversight means responsibility
for ensuring that everything in the sandbox complies with Apache Software Foundation policies.
Though (it is to be hoped that) committers should be able to be trusted, in the last resort
the Commons team reserves the right to remove offending material from CVS. 

If questionable material is found, the right way to proceed is to first raise the matter on
the commons-dev mailing list. The community will form a judgement about the material and the
committers will be able to respond. It's a good idea to inform the committers directly (in
case they are not on the list). It's also a good idea to copy the Jakarta PMC. 


= The Commons Proper =

The Commons Proper consists of small, reusable components each developed independently.

= Commons Committers =

The commons proper is governed by the same membership rules as any other jakarta subproject.
That means committers are elected. Unlike the sandbox, there are no automatic rights for existing
Jakarta committers. 

On the other hand, the barrier to entry for existing Apache committers has traditionally been
pretty low. If you express an interest, show willing by creating a few patches and you're
known to existing committers, there's usually no problem. VOTEs proposed by commons committers
for existing jakarta committers listing their achievements have (in the past) been passed
very quickly.

= Commons Etiquette =

Every commons committer has karma to every component. But a point of etiquette (enforced by
the charter) is that each committer who commits to a component must add their name to the
STATUS file for that component. It's also good form to post a message saying 'hi, i'd like
to get involved with component foo' before you dive in. Traditionally, adding your name to
the STATUS file is a committers first commit on a component.

There is one important point about the list on the STATUS file. It is used to work out whose
VOTEs are binding. (Since there are a lot of commons committers, this is more useful than
it might first seem.) If you're name isn't on the list, your vote won't count :)

= VOTEs =

The commons-dev mailing list is a busy place. Very much a bazaar rather than a Cathedral.
This means that VOTE threads have a habit of petering out. It a good idea to post a <tt>[VOTE][RESULT]</tt>
which counts the binding VOTEs and tells people the result. 


= Promotion =

Promotion is the process by which components move from the sandbox into the commons proper.

Promotion to the commons proper is not the only route out of the sandbox. The commons proper
isn't always the best place for all components from the sandbox.  There isn't any reason why
a component couldn't move directly from the sandbox to become a project or a subproject. At
least one component has moved from the sandbox to sourceforge and then finally back to the

Promotion is basically a beauty contest. If the component can win enough votes and few enough
people vote against it, then the component is promoted. But there is one thing that is most
definitly required:

* Compliance with Apache Software Federation policies. This means a full license at the top
of every file. It means auditing the dependencies. It means ensuring the copyright date is
correct on the licenses.

There some points of etiqutte and a few criteria that (though they are not rules) often seem
to influence the voting.

* Evidence of compliance with the charter. This means having the documents required in the
charter including a PROPOSAL. (Please look through the charter.) Please list all committers.
Something like 'all jakarta-foo committers' isn't acceptable - a list is needed. 

* A good PROPOSAL. A good PROPOSAL is clearly written and tightly scoped (ie. specific rather
than general). Commons components are small, resuable components. The commons does not do
frameworks and anything frameworkesque is likely to be viewed with scepticism. A PROPOSAL
that duplicates an existing component will probably be viewed with suspicion. This is not
because duplication is disallowed (overlapping components are specifically allowed by the
charter) but because it indicates that the PROPOSAL fails to indicate the essential difference
between the proposed component and the existing one. For example, a PROSPOSAL for a small,
fast, compact xml-object mapper with minimal dependencies would be more likely to succeed
than a PROPOSAL for 'a better version of commons-digester'.

* The health of the development community. Fellow committers need to be persuaded that users
will be supported and the code pushed forward by the listed committers. This is a major issue
since there's only a limited amount of energy amongst the commons committers and no one wants
to have to support a component whose committers have gone AWAL.

* The people proposing the component. It's a sad fact of life but a PROPOSAL that comes from
well known and respected Apache committers is more likely to be viewed positively than a PROPOSAL
by people not well known to the Commons Team. Please don't get offended - you'll just need
to work that little bit harder.

= Ettiquette - Proposing A Promotion VOTE =

* Discuss and try to formulate a consensus first. Promotion votes can (and do) get messy unless
this happens. Create a discussion thread on the list and try to find out any reasons people
might have for voting against. You might need to alter your charter, add missing files or
resolve dependency issues. It's easy for everyone if all main issues are sorted before you
propose the proper VOTE. If revisions to the proposal are required, the VOTEing can get very

* Post a promotion email whose subject and body make it clear that this is a formal promotion
VOTE. The subject should be prefixed by <tt>[VOTE]</tt> and should be something
like <tt>[VOTE] Promote commons-foo</tt>. The body should be clear and fairly

* Proposal - always include a copy of the PROPOSAL that's being VOTE'd on in the VOTE email.
This is important since it is clear to everyone what they are VOTEing on. It also prevents
being put in the embarasing position of the PROPOSAL being VOTE'd on being modifed in CVS
half way through a VOTE thread. 

* Please give the proposal enough time to give everything the chance to VOTE. I leave promotion
VOTEs several days - maybe up to a week. When VOTEs have stopped coming in then please the
proposer should post a <tt>[VOTE][RESULT]</tt> giving counts. Only the VOTEs of
commons committers are binding so please make sure that these are tallied separately. The
reason why a result email is good is that VOTE thread tend to peter out and so without a final
email, it's hard to look back through the archives and find out what's happened. Another reason
is that it's a good way to let everyone know what the result was. If there are any disagreements
about the result, they can be resolved then. 

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message