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 requested. Incubator is the responsible top level project.
So the domain MUST
be incubator.apache.org
.
For example:
- dev@${podling}.incubator.apache.org
- commits@${podling}.incubator.apache.org
- private@${podling}.incubator.apache.org
For initial community building it is usually appropriate to only have
a "dev" list, to keep the discussions focussed. Later add a "user" list
if needed.
Commits under http://svn.apache.org/repos/asf/incubator/${podling}
will be emailed to commits@${podling}.incubator.apache.org
.
Any deviation will
require special configuration in the asf-mailer.conf
file by the IPMC.
Mailing lists creation is a task for the infrastructure team. The
infrastructure team offers a tool that simplifies the creation of mailing lists. You can access the
Incubator Mailing List Request Form
to request a list. A notification will be sent to private@incubator when the lists have been created.
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.
Once the commits
list is created, the project MUST review
the /incubator/${podling}
tree, since any commits made prior
to the list's creation will have generated no email trail.
Mail Archives
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 (and moderated) to these lists.
You can also leverage lists.apache.org for
mailing list archives. There is a login link in the top right corner, which allows you to respond to
threads from within the web application.
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.
Mailing List Administration
Apache uses ezmlm. See the
manual and
committer mail FAQ
for more details.
Mailing List Transition
Independent mailing lists and groups are perfectly acceptable but development should
happen on the official mailing lists at Apache. If a project has existing mailing lists,
forums or groups the community needs to consider their future and plan for the transition
to the official Apache mailing lists.
It may be useful to move development first to the official lists followed gradually
by the user resources.
Note that subscribers of external mailing lists will not be automatically subscribed
to the new Incubator project mailing lists. Instead, a note should be posted to the
old external mailing list asking them to subscribe to the new list. If possible, add
a footer to the old mailing list with some instructions.
Issue Tracking
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 file an INFRA issue using the 'new jira project'
type (not bug or request)
Remember to post an email announcing that the issue tracker is available.
The most important responsibility for mentors is to set up the
podling source repository. Podlings can choose between svn and
git for source control.
Set up GIT Repository
Requests for new git repos are done via reporeq.apache.org.
This service will initialize a new repository, setup github mirrors and enable integrations for that repository.
The Foundation's policy
is to grant access to git repositories broadly to the incubator group,
not narrowly podling-by-podling. So, once the repository
exists, incubator group members gain access without further work. Once
the podling graduates, a dedicated ldap group will be created to manage
access and only those members will be given access.
Set Up SVN Repository
If the podling chooses svn, you must create the
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.
Setting up a podling subversion repository has two steps: Creating the SVN space
and configuring the authorization (in both svn and git).
Create 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}
Create the workspace authorization in asf-authorization-template.
This requires commit access to infrastructure-puppet
to modify the file
https://git-wip-us.apache.org/repos/asf?p=infrastructure-puppet.git;a=blob;f=modules/subversion_server/files/authorization/asf-authorization-template
.
Please follow the procedures in the infrastructure puppet workflow document.
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, to enable the podling for its
eventual website:
[/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.
Authorize Committers
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:
-
Ask developers to send their ICLA to secretary@apache.org according to
standard procedure.
Note that ICLA forms must be signed, either by hand or by digital signature.
-
Developers should choose an Apache id that is not already listed
here.
-
Developers should enter their preferred Apache id on the ICLA
and enter the podling name in the "notify" field of the ICLA.
- 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.
NOTE This section is a DRAFT under development.
Following podling creation, it needs to be bootstrapped. Here are some of
the tasks:
- Ensure Mentors are on the IPMC[
Mentors
]
- Add podling to reporting schedule [
IPMC member
]
- Initialize project status page [
IPMC member
]
- Start orientation [
Prospective committers
]
- Start
CLA
and CCLA
submission [Prospective committers
]
- Start IP Clearance
[
IPMC member
]
- Request Required Resources
- Mailing Lists [Infrastructure Team]
- Subversion [IPMC]
- Issue Tracking [Infrastructure Team]
- Create website [
Prospective committers
]
- Consider and plan web site transition
Mentors MUST be on the IPMC
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
.
This process may take a few days.
CLA and CCLA Submission
Prospective committers need to submit a
Contributor License Agreement
(CLA).
This process can take a while so it is recommended that committers start to submit
these as soon as the podling is accepted.
IP Clearance
Background
Existing codebases need to be imported through the standard IP clearance
process. This means that a Software Grant Agreement
(SGA)
or Contributor License Agreement
(CLA)
need to be submitted
for all copyright owners. This process may take a while so it is 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.
Establishing Provenance
Paperwork needs to be submitted to Apache that grants a legal license on the code
to the Apache Software Foundation.
As a rule of thumb, if all the material contributors to the code
are joining the podling as initial contributors, then CLAs (individual or corporate)
are all you need. The individuals must submit the 'individual' CLA (ICLA).
If there are employers involved who might claim
rights in the code, then corporate CLAs (CCLAs) are needed for those employers.
If, on the other hand, there are material contributors who are
not joining the podling as initial contributors, or if there
are additional corporate entities who can claim rights in the code,
then SGAs are required from those individuals or corporations.
The foregoing is only a rule of thumb. Generally, the mentors of a new project
will need to consult with general@incubator.apache.org or the Apache legal team
about the particular circumstances.
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.
Initial Code Dump
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.
Importing History
The incoming code can either be committed as a snapshot or as a complete version
control export including history (provided that the import is available in a format
readable by subversion).
Importing with history allows existing open source projects who want to maintain
older versions at Apache to easily perform source diffs and so on. Import just the
latest code allows a clean break to be made with the past. The choice is left to
the community of the incoming project.
The infrastructure team will perform the import including
mapping IDs but it is an operation that requires skill, time and care. In this case,
please ask the infrastructure team politely.
Audit Cryptography
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.
Initial Clean Up
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.
Clean Up Best Practice
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.
On Repackaging
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.
Update Documents
Check the documentation for references to the old home of the project and update them
with references to Apache.
Read
Branding Guide.
Ensure that appropriate disclaimers are added to the appropriate documentation.
Consider adding a DISCLAIMER
text document.
Update Build
If the project uses Apache Maven, the pom will
need to be updated to reflect that the project is now at Apache. In particular:
- Update
mailingLists
- Update
organization
- Update
url
- Update
issueManagement
- Check
licenses
- Update
scm
- Update
groupId
- Update
manifestEntries
. It is recommended that the
standard Apache settings are used
- Update
developers
to use apache IDs (when known)
- Update
distributionManagement
- Consider specifying a relocation
If the project uses Apache Ant, the build script
will probably need to be updated. In particular:
- Ensure any MANIFESTs generated refer to Apache. It is recommended that the
standard Apache settings are used.
- Check that
LICENSE
, NOTICE
and - if appropriate -
DISCLAIMER
documents are copied into binary artifacts
Orientating New Committers: Understanding Apache
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 discussions 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.
Mentors need to take care. During the initial bootstrapping a habit may develop
of emailing private list. It is important to break this habit as soon as the mailing
lists are available.
Netiquette about the correct use of cc
's may also be difficult to
effectively impart. During the bootstrap process there are a number of occasions
where cc
's are required. The typical usage is to copy in a private
listing to indicate that the action has the lazy permission of the committee.
cc
's are very commonly used to create inefficient ad-hoc mailing lists in
the commercial world. Except for a small number of defined processes, cc
's
are frowned upon at Apache. Mentor need to encourage questions to be asked first
on the public lists of the project then raised (if necessary) to the general
incubator list.
TODO: content, links, prose, reconsider name for this section
Issue Tracking Transition
Issues for Apache projects should be tracked on Apache hardware. Some projects arrive
with existing issues tracking. So, in the end these need to be replaced (for new development
at least) by the Apache issues tracker. Options need to be discussed publically on list
and a consensus reached about the best transition strategy.
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://${podling-name}.incubator.apache.org/
.
However, the infrastructure team has some requirements for the publication
process to manage the load on servers. The page linked below on the Apache CMS
has more information.
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.
Web Site Transition
Projects may arrive with existing web sites outside Apache. Contributing as much
documentation as possible to the project from these sites is strongly encouraged.
Offshore sites related to projects are fine but official web sites for Apache
projects should be hosted by Apache.
Some projects elect to maintain previous releases outside Apache. In this case, the existing site
is typically retained as a hub for this maintenance work. Otherwise, sites should link
or redirect to the official Apache site.
Apache may accept donations of domains related to projects moving here.
Infrastructure will then arrange for renewal of the domains and redirection
of traffic the official site. Ask infrastructure for more details.
Apache needs to deal with all commercial entities equitably. Linking to
useful information on commercial sites is fine but unfair discrimination between
commercial sites is not. Most Apache projects find it better to simply link only
to relevant articles on commercial sites rather than having to vet every request
for links to commercial activity.