|
The intent of this document is to help podlings
understand the process of
graduation and offer some views about how to approach it.
It also links to the Incubator
exit policies.
It is not an inflexible standard but represents a
consensus condensed from previous discussions on the
incubator general list. It also describes some of
the first steps that should be taken after
graduation.
This is just a guide. Policy is stated
here.
Help to improve the system by posting a patch for
this document to the incubator section of JIRA or a
comment to the general list at
incubator.
Graduation is the act of a podling becoming either a
subproject under an already existing Apache project, or
becoming a top level Apache project. Graduating is a
democratic process: in the end, it comes down to a VOTE . Note
that during your stay in the incubator, you are already busy
with the process of Graduating: by adopting Apache procedures,
growing and fostering your community, having (civil) fights
concerning code style (tabs versus spaces), cutting releases
and so forth. All these acts have an influence on your
projects graduation.
The road to graduation pretty clear: depending on wether your
project wants to become a top level project, or join as a
subproject under an already existing project the steps are
fairly simple but do take time and effort. This document
provides guidelines for making this process run smooth.
This document is offered for guidance and education only.
Actual policy is documented in the Incubation Policy
Guide in this
section. Please post any questions about graduation
to the general incubator list.
Each proposal has a Sponsor.
The identity of the Sponsor indicates the natural
destination. For proposals sponsored by the Board or by
the Incubator
PMC (IPMC), this is a top level project. For others,
this is as a subproject of the sponsoring project. However, the
destination is fixed only on graduation, not entry. Projects
grow and evolve during the graduation process. As
graduation approaches, this original preference should be
reviewed based on where the project is now.
Graduation as a subproject is only possible if the
subproject still falls within the scope of the project and
requires the consent of the project PMC.
Graduation as a project requires the formation of the new
project by the Board.
The IPMC
will also express a democratic opinion. For those seeking
to graduate to a subproject this VOTE
is to approve the
transfer. For those seeking to graduation as a top level
project, this will be a recommendation to the Board.
Expect IPMC-ers to ask questions about the project
including about the choice of destination. This is part of
the normal process.
Before you start thinking about graduation, you need to make
sure you are ready and meet the requirements imposed on Apache projects.
This section will provide a shortlist for podlings to
determine if they meet the criteria for asking graduation.
The following is a short checklist giving an overview, not
a substitute for reading the content below.
- Preparations
-
Decide upon destination
-
Prepare a resolution
(top level candidates only).
-
Subproject acceptance
VOTE by destination Project (subproject
candidates only)
-
Incubator PMC (IPMC):
-
Final hand-over
-
Consider post graduation tasks
The status file records and summarizes incubation-related
information on the podling. The PPMC is
responsible for keeping this file current. Before you are
able to graduate, all tasks need to be completed.
The status file is a great way of keeping tabs on how your
project is doing and what needs to be done to meet the
graduation criteria. The Incubator PMC
will check this
file when they vote on the graduation of your project.
Once all tasks are done and the listed criteria met, your
project may be ready for graduation.
The status file of the JUDDI project is one
example.
Release Early, Release Often
Projects need to cut releases. Apache projects need to
understand how to cut Apache releases. Therefore it is an
important step during your stay in the incubator to
demonstrate the ability to create an Apache Release.
Podlings do not need to actually publish a
release to demonstrate that they understand how to
accomplish such a feat. However, creating a release that
is approved by the
incubator project management committee is usually the
simplest way to do this.
If you are going to cut a release (which is highly
recommended), then please read the Incubator Release Management
Guide for hints, tips and guidelines for cutting a
release that will get approved by the IPMC
without problems.
A major criterion for graduation is to have developed an
open and diverse meritocratic
community. Time has demonstrated that these kinds of
communities are more robust and productive than more
closed ones.
Apache projects are self-sustaining and self-governing
communities. Long term success and health requires that
these communities understand how to:
- recruit users, developers, committers and PMCers
- take responsible collective action
- disagree in public on technical matters without destroying personal relationships
- create an open, positive and inclusive atmosphere on the mailing lists
Graduation tests whether (in the opinion of the IPMC)
a podling has learned enough and is responsible enough to
sustain itself as such a community.
Read more on how to successfully build an open and diverse
community for your podling in the community guide.
As a project grows, it needs to renew itself by accepting
new committers. A project needs to learn how it can
recruit new developers and committers into the community.
Accepting new committers usually increases the diversity
of the project. So, this process is very beneficial. Community building requires
energy which could have been spent on code development but
this cost is an important investment for the future of the
project.
The openness of the community is not only measured by the
number of contributors. Open and respectful discussions on
the mailing lists are vital. Ways to resolve technical
conflict without destroying personal relationships must be
learned. Learning to use mailing lists effectively is very
important. If this can be achieved, then you have shown to
be a lively, active and successful community. The future
looks bright.
The project is considered to have a diverse community when
it is not highly dependent on any single contributor
(there are at least 3 legally independent committers and
there is no single company or entity that is vital to the
success of the project). Basically this means that when a
project mostly consists of contributors from one company,
this is a sign of not being diverse enough. You can
mitigate this requirement by admitting more external
contributors to your project that have no tie to the
single entity.
Growing an open and diverse meritocratic community is not
something that just happens: it takes work. Read the building a community guide for
guidelines, hints and tips on how you can accomplish this
for your project.
The Incubator relies more on people than rules: rather
than try to create rules to cover every circumstance,
rules are developed and codified as required. People
are trusted to evolve process and policy. This guide
can only document the most common issues and it is
possible that there are other concerns that may require
resolution that are not covered.
Top level projects are created by the Board. The Incubator
Project Management Committee (IPMC) can therefore only
recommend to the Board that the project is ready to
graduate to a top level project.
Graduation to a top level project requires:
- a charter for your project
- a positive community graduation
VOTE
- a positive IPMC recommendation
VOTE
- the acceptance of the resolution by the Board
This process can take a while, since it typically sparks
some discussion inside the community and possibly in the
IPMC.
Here's an estimated timeline for the graduation process.
It should help you understand when you should start
ramping up your community to get timely graduation and
make the process smooth.
For each event we scheduled one or two weeks. Even though
a VOTE
is usually limited to 72 hours, you should prepare
for discussion and possibly having to cast a revote with a
revised proposal.
A community needs to be willing to govern itself
before it can become a top level project. A good way
to demonstrate this is through a free VOTE (by the
community) on the graduation proposal.
This VOTE is not a requirement but is recommended. It
is unlikely that IPMC
members will vote to approve graduation unless the Mentors
and community positively express their readiness for
graduation. It is wise to copy the incubator
general list when the vote is proposed.
So, in this case a suitable Board resolution should be
drawn up by the community advised by the
Mentors.
Committers can access the podling template for
resolutions in the committers
svn repository. Also, resolutions are included in
the Board minutes, which are posted publicly
here . These contain numerous examples. Good
examples include:
The original proposal and the status document should
be consulted when creating this document. Projects
evolve over time and some deviation from the original
proposal may well prove acceptable. The Board
resolution is the ultimate definition of the scope of
an Apache project. So, it is important that it
reflects the vision for the project as it appears on
the eve of graduation.
A good resolution is neither too narrow nor too broad.
If the project's scope is too narrow, then its
activities will be unnecessarily constrained. If a
project's scope is too broad then it may lack focus
and suffer from governance issues.
If you read these resolutions you also see that you
need to appoint a Chair
for your project. It is up to the
PPMC to choose one
person to act as the chair after graduation.
The resolution should be proposed on the general
incubator list before a VOTE
is started to allow feedback. Once a consensus has been reached, a VOTE
should be started on the same general incubator list by a member of the PPMC proposing
that the IPMC
recommends the resolution to the Board.
Top level projects are created by a resolution by the
Board.
Once the resolution has been
finalized and consensus reached, it should be
submitted to the Board. For inclusion in the agenda
for the next meeting, the resolution should be
submitted at least 72 hours before that meeting. A
calendar for meetings is available.
Business for the Board should be submitted by a post
to the board mailing list. Posting from
an Apache address is recommended. Mixing public and
private lists on a post is not recommended.
The board list is private.
The usual netiquette
for Apache private lists should be observed. So, it is
recommended that only the podling and IPMC
private
lists are CC'd (rather than the general incubator
list). Please treat responses with appropriate
confidentiality.
The submission should include:
- A clear subject (for example Establish Foo TLP)
- A brief introduction
- The name of proposed VP
- Links to the
VOTE threads
- Summary of the
VOTE results
- The resolution text
For example:
--
From: <you _at_ apache dot org>
To: <board _at_ apache dot org>
CC: <<project>-private _at_ incubator dot apache dot org>
Subject: proposed resolution: establish <project> TLP
Dear Apache Board,
<Project> is ready for graduation out of the incubator. So, please
consider the draft resolution below at your next meeting.
<thank you, best regards, personal note if you wish, etc etc>
<your name>
--
References:
Home: <project home page>
Vote by project: <link to vote thread on project list>
Vote by incubator: <link to vote thread on general list>
Resolution draft:
<<resolution goes here, 72 characters wide,
indent with 4 spaces>>
--
<your e-mail sig, if you have one>
Please try to keep the board list traffic low. Do not
submit reminders or ask whether messages have been
received on the list. Apache
Members have access to the Board
archives and may
observe Board meetings. To follow the progress of a
resolution, please ask a friendly Member or Director.
Subprojects are accepted by a Project Management
Committee. The Incubator Project Management Committee
needs to approve the graduation of the podling to a
subproject.
A community needs to be willing to govern itself
before it can become a top level project. A good way
to demonstrate this is through a free
VOTE
(by the community) on the graduation proposal.
This VOTE is not a requirement but is recommended. It
is unlikely that IPMC
members will vote to approve graduation unless the Mentors
and community positively express their readiness for
graduation. It is wise to copy the incubator
general list and the sponsoring
top level project when the VOTE
is proposed.
A formal VOTE
by the Project PMC
to accept the podling as a subproject is a
prerequisite. Sometimes, projects may feel that the
podling has grown too big and would be better as a
top level project. The Chair of the project is the
right contact.
To graduate as a subproject, the Mentors
should start a VOTE
thread on the general
list proposing that the
IPMC signs off the graduation of the podling as a
subproject. This VOTE s should only be started once the
project has VOTE d to accept the subproject.
This is the transfer of virtual resources from the care of
the IPMC
to the care of either the new or existing top
level project taking charge of the graduating community.
This is the simple case. The IPMC
Chair and the Chair of the project accepting the
graduating community organize the handover between
themselves.
When graduating to a new project, the process is more
complex. Creating a new project requires a resolution
to be passed by the Board.
Usually once this happens, members of the Board will
inform the appropriate chairs and PMCs.
Occasionally, this will be missed: if more than 72
hours has passed since the Board meeting, it may be
worth someone posting a polite reminder to their
favorite director.
The
resolution will appoint a Chair for the new
project. The Chair will also be appointed an Officer
of the Apache Software Foundation. This allows them
access to official resources of the foundation as well
as granting power to act on behalf of Apache.
Once appointed, the new Chair needs to:
- Subscribe to the
board mailing list
- Subscribe to the
infrastructure mailing list
- Ensure that they have been added to the PMC chairs group in svnauth.
There are various ways to discover whether has been done:
-
Ask a friendly Member.
-
Examine the
asf-authorization file.
This is found in the
https://svn.apache.org/repos/infra/infrastructure/trunk/subversion/authorization/
directory of the private repository.
Note that new Chairs without infrastructure
karma will be unable to checkout this directory from
subversion until they have PMC chair karma. So, checking
out this directory is a reasonable test.
-
Watch for the infrastructure commit to
asf-authorization .
- Check out the
foundation/officers folder from the private repository.
- Add yourself to the
foundation/officers/affiliations.txt and the foundation/officers/irs-disclosures.txt files with the appropriate information.
- Review appropriate documentation:
-
Work out a reporting schedule with the Board. For
the first three months after graduation this will
be monthly. After that, the project should slot
into a quarterly reporting schedule. Now is a good time to remove
the project from the Incubator reporting schedule.
-
Work with the Apache Infrastructure team
to set up the top level project
infrastructure. The various infrastructure tasks that are required
(see check list)
should be consolidated into a single issue (see this
for example). This should be created in the category
TLP Admin.
- Add the new project to the foundation web site. You will need a member to help with this task. Instructions for updating the web site are here.
- Add the new project's PMC chair to the
foundation/officers/irs-disclosures.txt file. You will need a member to help with this task.
They should then be able to start assembling the new
PMC.
The starting membership is listed in the
resolution. However, the Chair of the new project
needs to ensure that private list is created and the
membership subscribed.
Members of the new PMC need to:
- Subscribe to the private mailing list for the project
- Review appropriate documentation:
Once all this is in place, resources can start to be
handed over to the new project.
Please continue to hang around the Incubator and help
new podlings have an easier time than you did!
Graduation is the first step in what is hopefully a long road.
There are some issues which incubation may not cover.
When a project graduates, then the infrastructure
resources (mailing lists, websites, source, etc.) need to
be transferred from the Incubator to a project's new home.
Checklist:
- Source
-
Post an announcement to the development list
telling everyone that the repository is about
to be moved
-
svn move the podling source tree
-
Post an announcement containing instructions
for developers describing how to
svn
switch their workspaces
-
Update site, wikis,
pom.xml and
other resources to point to the new repository
location.
-
Websites
- Transfer the podling website
-
Load the website into its new home.
See infra
notes.
-
Update the
incubator/site-publish/.htaccess entry to
redirect traffic from the old URLs to
the new. (svn location is at http://svn.apache.org/repos/asf/incubator/public/trunk/site-publish/ )
-
Delete the podling website from
/www/incubator.apache.org
on people.apache.org .
-
Post an announcement to user and
development lists
-
When using Maven: update
pom.xml for the location
of the website, as well as the place
where the site plugin will deploy the
web site (when applicable).
- Update the Incubator site
-
Update the Incubator status
page
-
Update the podling status page.
All sections should now be filled in
including EXIT. Take some
time to read carefully since this page
forms the final public record for
graduation.
-
Edit the Incubator website to remove the podling
from the list in
project.xml . Here explains how.
- Wiki
-
(Top level projects) request
a new wiki (if it is a moinmoin based wiki).
-
Transfer podling related content from the
Incubator
wiki to the project wiki
-
Make sure your documentation points to the new wiki address
-
Post an announcement to user and development lists
-
(Top Level Projects Only)
Add Project To
www.apache.org
-
Check out
https://svn.apache.org/repos/asf/infrastructure/site/trunk
-
Patch
xdocs/stylesheets/project.xml
-
If you have karma, regenerated and
apply patch
-
If you do not have karma, submit
patch to
infrastructure JIRA
- Mailing lists
-
Request
that podlings lists be transferred to their new
home. Any new mailing lists should be requested at
the same time.
-
When this has been executed by infrastructure,
post an announcement to user and development lists.
-
When using Maven: update
pom.xml for
the new mailing list address(es). Also update any
documents on your website that show how to
subscribe to the lists and/or find archives.
-
Send notice to nabble.com (if they
archive your incubator mailing list) that the
address has changed, and possibly the location of
your project (if it is listed as being part of the
incubator). Repeat for other known mailing list
archivers.
-
Update website: replace links to old archives with
links to new ones and add new links to historic
archives from incubation.
-
Check project-private mailing list membership.
Mentors should be allowed to remain if they wish to
do so. The subscriber list should otherwise match
that on the resolution. See
this and the EZMLM
"Moderator's and Administrator's Manual".
-
Update mail addresses including:
-
svn commit messages (see
infrastructure/trunk/subversion/authorization/asf-mailer.conf
)
-
confluence commit messages (see adminstration documentation)
-
issue tracking messages (see administration documentation)
The chair should have karma to perform these
tasks.
- Issue Tracking
-
Check that the issue tracking system used by the
podling reflects the project's new status.
When a project graduates, then the incubator resources
need to be updated to indicate that the project is no
longer incubating. Here are a few of the items that need
to be done:
-
Update the svn
incubator/trunk/site-author/projects/${project}.xml
file to show the project's status.
-
Remove the project from the reporting calendar
w.a.o/incubator/ReportingSchedule
-
Remove the project from the right-hand navigation bar of
the incubator web pages by updating svn
incubator/trunk/site-author/stylesheets/project.xml
and re-generate the whole site.
-
In the Incubated Projects table, move
the project's entry from the "Currently in incubation" section
to the "Graduated from incubation" section, i.e update the svn
incubator/trunk/site-author/projects/index.xml
-
Ensure that other svn resources for your project have moved to
your new home.
-
Review this whole graduation guide.
-
Edit this guide to add missing steps and clarifications.
During the stay in the Incubator, the
Incubator PMC (IPMC)
was responsible to the
Board
for oversight. A graduated project must now take
responsibility for it's own oversight.
A project needs to ensure that it's code base is
clean from an IP perspective. New committers need to
recruited, educated and mentored. Quality releases
need to be cut. Community spirit needs to be maintained
and conflicts resolved positively. Board reports need
to be accurate and prompt.
Help is still available but the
appropriate bodies (infrastructure, community, legal
and so on) should now be approached directly.
Each project needs to be able to manage security issues
discovered in their code. By their nature, these issues
need to be dealt with in private. These issues may either
be dealt with on a separate security list or on the
private list. Which list is suitable for security issues
should be noted.
Volunteers need to be found from the
PMC
to work with the Apache security team and act as
first contacts on security matters. The new project
should make contact with the team soon after graduation
and not wait for the first issue to be raised.
Projects should adopt a positive attitude towards
security issues. It is easy to gain a poor reputation
by mishandling of these issues. There are many people
at Apache with considerable experience in this area
so ask first.
Passing through the incubation process gives a very
valuable perspective. Please help to improve the process
by guiding new podlings and by developing improved policy
and documentation on the general list.
|
|