Guide to Successful Graduation

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.

What is Graduation?

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 is pretty clear: depending on whether 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.

Whether to Graduate to Subproject or to Top Level Project

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 Graduate

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.

Graduation Check List

The following is a short checklist giving an overview, not a substitute for reading the content below.

Preparations
- Complete (and sign off) tasks documented in the status file
- Ensure suitable names for project name and product names
- Demonstrate ability to create Apache releases
- Demonstrate community readiness
- Ensure Mentors and IPMC have no remaining issues
Decide upon destination
Prepare a resolution (top level candidates only).
Subproject acceptance VOTE by destination Project (subproject candidates only)
Incubator PMC (IPMC):
- For top level candidates, this is a recommendation VOTE
- For subproject candidates, this is a graduation approval VOTE
Final hand-over
Consider post graduation tasks

Checking the Status File

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.

Ensure suitable project name and product names

Please read detailed documentation here. The "Process for ensuring suitable project and product names" is mandatory for every podling which wants to graduate.

Creating an Apache Release

Release Early, Release Often

Eric Steven Raymond

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.

Creating an Open and Diverse community

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.

Other Issues

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.

Podlings who are unsure if they are ready to graduate may want to consider completing the Apache Project Maturity Model. You may find this to be a useful guide when looking at various factors in your podling's community.

The Graduation Process

Graduating to a Top Level Project

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.

Community Graduation Vote

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 notify the incubator general list that the community vote is starting. Please do not Cc the vote to the general list as that creates confusion, instead you can either:

FWD the [VOTE] e-mail to the general list, or
Send a different copy to the general list indicating that a graduation community [VOTE] is in progress

Preparing a Charter

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:

Harmony (see section E. Establish the Apache Harmony project in the October 2006 Board minutes)
OFBiz (see section B. Establish Apache Open for Business Project in the December 2006 Board minutes)
Cayenne (see section C. Establish Apache Cayenne Project in the December 2006 Board minutes)

Click here for a template of this proposal to use.

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 Recommendation Vote

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.

Submission of 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.

Press Releases for new TLPs

Once there is clear consensus that the recommendation will happen, a member of the PPMC should contact ASF Marketing & Publicity at press(at)apache(dot)org if your project is interested in a formal press release announcing your graduation. This should be done roughly at the same time that the board resolution is sent.

Graduating to a Subproject

Subprojects are accepted by a Project Management Committee. The Incubator Project Management Committee needs to approve the graduation of the podling to a subproject.

Community Graduation Vote

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. When this vote starts, you should notify the Incubator and the Sponsor. Please do not Cc the vote to these lists as that creates confusion, instead you can either:

FWD the [VOTE] e-mail to the list(s), or
Send a different copy to the list(s) indicating that a graduation community [VOTE] is in progress

Subproject Acceptance Vote

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.

Graduation Approval Vote

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 VOTEs should only be started once the project has VOTEd to accept the subproject.

Life After Graduation

Handover

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.

Graduating as Subproject

This is the simple case. The IPMC Chair and the Chair of the project accepting the graduating community organize the handover between themselves.

Graduating as New Top Level Project

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 (pmc-chairs) in LDAP. The ASF Secretary should do this without any action on the part of the new chair. As with above, if it has not happened within 72 hours of the resolution passing, contact the secretary to remind them.
Check out the foundation/officers folder from the private repository. Users with member or pmc-chairs karma can do this.
Add yourself to the foundation/officers/affiliations.txt and the foundation/officers/irs-disclosures.txt files with the appropriate information.
Add your details to the foundation web site Officer list at http://www.apache.org/foundation/index.html (in SVN at https://svn.apache.org/repos/asf/infrastructure/site/trunk/content/foundation/)
Review appropriate documentation:
- PMC Chair Duties
- PMC documentation
- Jakarta Chair guide
- Incubator Chair guide
- Reporting calendar
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.
Ensure the PMC is added to the committee-info.txt file at https://svn.apache.org/repos/private/committers/board/committee-info.txt
There are 3 sections which need to be updated; see instructions in the file. You may need to get a member to help with this.

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:
- Apache PMC Guide
- Related 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!

First Steps Outside the Incubator

Graduation is the first step in what is hopefully a long road. There are some issues which incubation may not cover.

Transferring Resources

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.

Although the below checklist is still generally useful, the infrastructure process has been streamlined, see http://www.apache.org/dev/infra-contact#requesting-graduation . You might also want to check JIRA checklist tickets for projects that graduated in the last month or two.

Checklist:

Update the Incubator status records
1. Like the rest of incubation, graduation is a process. Updating your status records as you progress will enable others to assist.
2. 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.
3. Update the Incubator status page to denote the project as "graduating" when you commence, then as "graduated" when you are finished. The notes below will assist.
Source
1. Post an announcement to the development list telling everyone that the repository is about to be moved
2. Post an announcement containing instructions for developers describing how to svn switch their workspaces
3. Update site, wikis, pom.xml and other resources to point to the new repository location.
Websites
1. Transfer the podling website
  1. Load the website into its new home. See infra notes.
  2. 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/content/.htaccess) - NOTE: new Top Level Projects will most likely get an automatic redirection of their website from the Incubator hostname once the TLP's distribution repository is moved by INFRA.
  3. Post an announcement to user and development lists
  4. 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).
2. (Top Level Projects Only) Add Project To www.apache.org
  1. Check out https://svn.apache.org/repos/asf/infrastructure/site/trunk
  2. Patch templates/blocks/projects.mdtext
  3. Commit, and if you have karma then publish the updated www site
Mailing lists
1. When your mail lists have been moved by infrastructure, post an announcement to your lists.
2. 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.
3. Send notice to any mailing list archivers that the address has changed, and possibly the location of your project (if it is listed there as being part of the incubator).
4. Update website: replace links to old archives with links to new ones and add new links to historic archives from incubation.
5. 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".
6. Update mail addresses including:
  - confluence commit messages (see adminstration documentation)
  - issue tracking messages (see administration documentation)
  The chair should have karma to perform these tasks.
7. Double-check that all of your lists have sufficient active moderators.
Issue Tracking
1. Check that the issue tracking system used by the podling reflects the project's new status.
Distribution mirrors
1. After you have a release at your new home (/dist/${project}/ area), remove any distribution artefacts from your old /dist/incubator/${project}/ area. Remember from the mirror guidelines that everything is automatically added to archive.apache.org anyway.

Final Revision of Podling Incubation Records

When a project has finished its graduation steps, 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/content/projects/${project}.xml file to show the project's status.
Update the podling summary metadata file, i.e. incubator/trunk/content/podlings.xml svn file. See the content/podlings.dtd and follow examples of other recent graduates. At the beginning of the process, add the "graduating" element. When finished the graduation process, then: Change the podling status to "graduated"; add the "enddate" attribute to document when the project graduated; add the "resolution" element (see other project examples); remove the "graduating" element.
After your project has finished reporting to the Incubator, then remove the "reporting" element from that podlings.xml file.
Ensure that other svn resources for your project have moved to your new home.
Review this whole graduation guide.
NOTE: Please edit this guide to add missing steps and clarifications.

New Responsibilities

Oversight

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 its own oversight.

A project needs to ensure that its 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.

Security

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.

Stay In Touch

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.