This document targets any Incubating Project member, but
especially Mentors, who have to ensure that some things get done.
For a general description of the role of a mentor on an incubating
project see the
Roles and Responsibilities
document.
This guide is a descriptive and at times
discursive document. It describes established practices.
It is informational not normative. Policy is laid down in the
Incubation Policy.
Once the Podling has been accepted by the Incubator PMC, the mentor
sets up
the Podling; i.e., creates the Podling status file and
either creates or requests that
other resources (mail lists, subversion, bug tracker, etc.)
be created.
The most important responsibility for mentors is to set up the
podling svn repository and give read/write access to the repository
to all the committers for the podling. This involves requesting
new committer accounts and granting access to mentors and existing
Apache committers.
Creating the workspace in svn. This requires commit access to the
incubator svn repository. Podlings are given their own subdirectory
of the incubator svn repository. To create the podling subdirectory,
the mentor executes the svn command to create a remote directory:
svn mkdir https://svn.apache.org/repos/asf/incubator/{podling}
Creating the workspace authorization in asf-authorization.
This requires commit access to the file
infrastructure/trunk/subversion/authorization/asf-authorization.
Edit the file to add the podling repository in alphabetical order, e.g.
{podling}={mentor1},{mentor2}
In the section listing all the projects, again in alphabetical order,
add the podling directory and permissions.
[/incubator/{podling}]
@{podling} = rw
This is a convenient time to add authorization for committers
who have accounts.
Authorization karma is restricted. If no Mentor
has this karma then post an email to IPMC private list requesting that this
is actioned.
The process to add committers to the podling depends on whether
the new committer is already an Apache committer and whether
the new committer is in the list of original committers:
The committer is in the list of original committers in the
podling proposal to the incubator and is not already an Apache
committer:
Remind the developers to send their ICLA according to standard
procedure. Ask each committer for their forwarding email address
and two (or more) ids, in case the preferred id is already taken.
Check the file foundation/officers/iclas.txt
or monitor the alias
foundation-cvs@apache.org
to see when the ICLA for new committers
is received. You can also check periodically on
Jim's List in the "Unlisted CLAs"
section. Once the CLA is received, send a message to root@apache
requesting that the new account be created. This request might
take several days depending on the infrastructure workload.
Once root has created the new account, the new committer needs
to be authorized to commit to the
podling repository.
The committer is in the list of original committers in the
podling proposal to the incubator and is already an Apache committer, only
incubator authorization is required.
The committer was voted by the PPMC and approved by the incubator
PMC:
Perform one of the above procedures depending on whether the
committer is already an Apache committer on another project.
The status
page is the incubator's record of the progress made.
It MUST be kept update to date during incubation.
Some of the information is available from the proposal.
As the startup process continues and resources are
created the status SHOULD be updated.
The template contains lists of actions which may be needed
to start up a podling. All those which do not apply should
be deleted.
The status page is a useful aid to workflow. Volunteers
can use it to sign up to the various tasks and monitor their
progress. Once the mailing lists are set up and prospective
committers subscribe then these may be used for discussion.
Mentors MUST be on the IPMC.
Any prospective Mentors who are not yet on the IPMC should ask to be added (by election).
Email the application to private@incubator.apache.org.
Prospective committers needs to submit either CLAs or CCLAs.
This process can take a while so it's recommended committers start to submit
CLAs and CCLAs as soon as the podling is accepted.
Existing codebases need to be imported through the standard IP clearance
process. This means that software grants or CCLAs need to be submitted
for all copyright owners. This process may take a while so it's best to
start as soon as the podling is accepted.
The acceptance of the initial codebases is approved by the
IPMC as part of the acceptance motion. So, no vote is required by the
PPMC. Otherwise, follow the standard IP clearance
process for podlings.
Paperwork needs to be submitted to Apache granting rights to use the
code. When code comes from existing close corporate sources,
then a SGA or a CCLA is typically used. When code comes from existing
projects consisting of individual contributions then each contributor
needs to be tracked down and asked to sign either a ICLA (if they
will be coming aboard the podling) or a SGA (if they will not).
It may take some time to track down all contributors. It is not necessary to
have paperwork on file for all contributions before the code is imported.
It may be necessary to reverse some patches and rewrite areas of code if
contributors cannot be found or at not happy about given Apache written
permission to use their code.
No releases are possible until the provenance of all the code to be release
has been clearly established and the relevant paperwork filed with Apache. It is
therefore important to keep the status updated.
Receipts of ICLAs, CCLAs, and SGAs are recorded by the secretary in
the private foundation repository. Reading is restricted to members and officers
of the foundation. If there is no officer or member available then ask on the
general list.
For corporate contributions, the SGA or CCLA MUST be completed, submitted
and received before the code is imported.
For contributions composed of patches from individual contributors,
it is safe to import the code once the major contributors (by volume)
have completed ICLAs or SGAs.
In either case, the code to be imported should be attached to a JIRA
and then imported. It is recommended that the previous version
control system is tagged so that the imported version is precisely known.
A public record MUST be made of the code imported. If the import is not
attached to JIRA then it MUST be committed to version control.
Before the code base is committed into an Apache repository, the contribution
MUST be checked
and any restricted cryptography reported appropriately. Read and follow
this guide.
Once a JIRA has been created, the source should be cleaned up.
Ensure source files use the standard Apache boilerplates.
This may mean replacing existing license headers. The
tools in
https://svn.apache.org/repos/private/committers/tools
and
https://svn.apache.org/repos/private/committers/relicense
may be useful.
Ensure that NOTICE and LICENSE documents are present and
correct
Add any required notices. Consider moving copyright
attributions from source documents to the NOTICE. Read
Apache policy on headers
.
Audit the source for any potential licensing issues. Any
which are found should either resolved immediately (when
required) or noted in the status document for later.
It is recommended that the initial clean up be is started
before the code is committed. It MUST be completed before any
releases are cut.
It is recommended that version control is used to create a
public record of the process. This will assist anyone
auditing the code provenance (now or in the future) to
easily perform due diligence without contacting the people
who performed the clean up. The clean up process should
therefore clearly document (using version control) the
evolution of the IP licensing.
Particular care needs to be taken with commit messages
during clean up. The intended audience needs to include
lawyers and code auditors. Members of the public need to be
able to follow and understand the process from these
messages alone.
It is therefore recommended that the initial source is
(after being expanded from the archive) checked in as is
into a special directory (
${project}/trunk/import
is suggested). The original packaging, copyright statements
and license notices should be preserved. A standard Apache
LICENSE and appropriate NOTICE should be added at the top
for the copyright for the collective work (see
policy
). Take particular care with this commit message. As with
any patch that contains code which is not the original work
of the committer, the JIRA url (for the artifact imported)
needs to be included together with notes about the original
copyright owner and any associated paperwork. The fact that
this is a exact import including original headers should be
noted to stop any queries about these foreign headers.
The cleanup should then proceed in a number of commits. If
the source provenance is complex, break the process up into
a number of logical steps committing each in turn with a
good message.
In particular, take care when relocating copyright
statements and license notices into the NOTICE in the root
directory: consider moving each copyright owner individually
so that it is easier to audit. (See
policy
.)
Once a section of code has been cleaned up
(and repackaged,
if necessary) normal development can begin.
It is recommended - but not mandated - that source is repackaged
under the Apache namespace. There is no need to use the incubator
namespace. For example, Java source might be repackaged to
org.apache.foo.Bar or a DTD to http://dtd.apache.org/foo/bar.
Existing open source projects moving to Apache may well need to consider
carefully how they will approach this transition.
The proposal should include a list of required resources. All of these will
require active set up. Some are created by infrastructure after an appropriate
request, others can be set up by any IPMC members (typically mentors).
Mailing lists should be created first. Other resources typically
post information to these lists.
Apache mailing lists require volunteer moderators. New moderators can be
changed later
but at least one volunteer is required before the mailing lists can be set up.
Moderation is a reasonably
easy task
though moderators may want to set up
spam filtering.
Having at least three moderators is recommended to spread the load.
The proposal should contain the rest of the information that needs to be collected
before the mailing lists can be set up. Incubator is the responsible top level project.
So the domain MUST be incubator.apache.org. Three lists are
typical. For example:
${podling}-dev@incubator.apache.org
${podling}-user@incubator.apache.org
${podling}-commits@incubator.apache.org
Commits under http://svn.apache.org/repos/asf/incubator/${name}
will be emailed to ${name}-commits@incubator.apache.org. It is therefore
recommended that the commit list is named
${podling}-commits@incubator.apache.org. Any deviation will
require special configuration in the asf-mailer file by the IPMC.
From: rdonkin@apache.org
To: apmail@apache.org
CC: private@incubator.apache.org
Subject: Mailing list creation for RAT
The Incubator Project has voted to accept RAT [1]
Please create the following mailing lists in the incubator.apache.org domain:
rat-private
rat-dev
rat-commits
Initial moderator for all lists: rdonkin@apache.org
JIRA: INFRA-1454 [2]
Thanks
- robert
[1] http://mail-archives.apache.org/mod_mbox/incubator-general/200711.mbox/...
[2] http://issues.apache.org/jira/browse/INFRA-1454
The email MUST be sent from an Apache email address. Typically this means
a Mentor, though any existing committer may make the request. Progress can be followed
via JIRA.
Remember to update the project status file with mailing list details. Prospective committers
and mentors will need to subscribe. Email them once the status file has been updated. Inform
any existing mailing lists or forums previously used by the project.
Archives at http://mail-archives.apache.org for the public
mailing lists will be setup as part of the mailing list creation process. No action is
required by Mentors. The archives will be visible
as soon as posts have been made to these lists.
Many projects are independently archived externally (for example, at
The Mail Archive and
MARC)
Independent archives help to
increase project visibility as well as preserving a independent historic record.
These subscriptions are not automatically created. If desired, subscribe manually.
Subscriptions to news-to-mailing-list bridges (for example, Nabble)
must also be created manually. Subscribing helps accessibility and visibility but Nabble news
users may not be aware that they are posting to a mailing list.
If any Mentor has project-creation karma (in the issue tracking system to be used)
then they should execute. If no Mentor has the required karma then post an email
request to the IPMC list. An IPMC member with karma will then execute.
Remember to post an email announcing that the issue tracker is available.
When a committer is elected by a typical top level project, the nominator
and other PMC members educate the new committer about Apache. In the Incubator, this
inductive must be performed by the Mentors. This process is one of the most important
for the long term health of a project.
Apache works on the principle that discusses should happen on the most open forum
available. Unless the matter involves a sensitive matter (such as security or
personal issues), it should be raised on an open mailing list (typically the podling dev list
or the incubator general list). Use of the incubator private list should be reserved
for official notifications and sensitive topics.
TODO: content, links, prose, reconsider name for this section
The board has charged the Incubator project with management of IP clearance for Apache.
Instructions are here.
These equally apply to podlings. The Incubator project is responsible for all podlings
and so is the receiving PMC. So, when a podling requests IP clearance, the
IPMC wears two hats.
This may be a little confusing at first.
The Incubator PMC must approve the clearance. This indicates that the project is
happy to receive the code donated. When a new podling is created, this is done
by the identification of existing codebases in the proposal. Otherwise, the
IPMC delegates this decision to the PPMC.
As usual, three binding votes are required. So, Mentors need to be involved in
IP clearance for podlings. If too few binding VOTEs are posted on list,
the VOTE will need to be posted to the general list for ratification.
The second hat is technical IP clearance. Here, the IPMC needs to check that the
paperwork is in order. Once the acceptance vote has been approved, an officer
or member need to complete the process. For a podling, this will typically
involve a Mentor.
Podlings are free to use any technology desired to generate static content to be
served under http://incubator.apache.org/${podling-name}. Some popular choices are:
It is recommended that an initial site is uploaded as soon as possible (to -
for example - allow indexing by search engines). The initial site
can be replaced by a fuller site later.
Read the
Podling Website Guide
for more information.
Apache Infrastructure does not guarantee that site content stored only on the www server
will be fully backed up in the event of failure. Consider checking the site into
version control if it needs to be comprehensively backed up.
Projects with an existing website who move to Apache need to consider
what they plan to do with it. A decision should be reached and action upon before
graduation.
Tasks that cannot safely be delegated to projects are handled by the Apache
Infrastructure team.
The relevant instructions
MUST be followed.
JIRA is typically used to
manage workflow. This allows progress to be easily tracked.
Edit the file to add the new committer to the podling authorization:
{podling}={mentor1},{mentor2},{new-committer}
Also add them to the relevant alphabetic group.
committers-{a-z}=...,{new-committer},...
If no mentor has karma then an email should be posted to the IPMC private
list requesting that the grant is performed. One of the IPMCers with karma
will authorize the committer.
