The Apache Incubator Cookbook

The Apache Software Foundation (ASF) provides software for the public good, as explained in our vision statement from 2018.

Our projects operate according to The Apache Way, a set of principles and best practices.

We put a strong emphasis on Community Over Code, fierce independence from companies and organizations, and openness in all aspects of our work.

Donating your project to the ASF means giving up control of it, and its trademarks, if any. You’ll be very welcome to participate in the project, but without a special status beyond being part of its Project Management Committee (PMC). The good news is that your project can then take a life of its own, with potentially a much broader reach, due to the ASF’s independence and emphasis on project sustainability.

Assuming your project fits this mindset, we do not link acceptance of your project to what it does, as the ASF on purpose does not have a technical strategy. If it’s very similar to one of our existing projects, we will probably ask you to consider joining that project. Still, some of our projects exist for similar purposes, and that’s not necessarily a problem.

To give our "podlings" (incubating projects) the best chances of success, we usually ask them to enter the Incubator with at least the start of a community built around an existing codebase.

The goal of incubation is to become an Apache Software Foundation (ASF) Top-Level Project (TLP).

See the How the ASF works page for what this means and what the various roles (committers, PMC members etc.) mean.

To achieve this, an incoming project ("podling") goes through the following steps:

Described above is the "happy case". Things might happen in a slightly different order, but it gives an overview of the typical incubation process.

Here are more details about these steps:

The Incubator PMC manages the Incubator and helps incoming projects in their journey through incubation.

To communicate with the Incubator PMC, use the public link:+https://lists.apache.org/list.html?general@incubator.apache.org [general@incubator.a.o] mailing list. That page has links to subscribe to the list.

To enter the Incubator, your project needs a champion and at least two or three mentors. These people MUST be Incubator PMC members, which ASF Members can join just by asking.

The Champion helps the incoming podling in the process of creating their proposal and acts as a liaison between the podling and the Incubator PMC for the initial steps, at least until the podling’s proposal is accepted. They may stay on to act as a mentor after that.

The Mentors accompany the podling through all phases that lead to graduation as a top-level project.

The starting point is usually to find a Champion. For that you might write to the general@incubator.a.o list with a brief description of your project, with relevant links, mentioning that you are looking for a Champion and trying to get people interested. Or, if you know any ASF Members or Incubation Mentors, ask them directly if they would be willing to help.

The Champion helps the podling prepare an incubation proposal that describes the incoming project for the initial discussions with the Incubator PMC.

The proposal needs to include several standard sections: see the podling proposal template.

Prior proposals are kept on the Incubator wiki. They can be consulted as examples, keeping in mind that the proposal template mentioned above is the current reference for new proposals.

Once the proposal is ready, the podling representatives send it to the general@incubator.a.o list for discussion, with a subject line like

to raise the Incubator PMC’s attention.

The discussion often leads to small or large changes to the proposal.

There’s no set duration for this discussion phase. It usually lasts for a few days until the discussion dies down and all discussion points have been addressed.

For recent discussions threads see:

Once the discussion phase is finished, the Champion or a podling representative starts a [VOTE] thread on the general@incubator.a.o list.

The vote happens according to the ASF voting rules. In short, it takes place on the Incubator email list, lasts at least 72 hours, and is a majority vote by the Incubator PMC members, with others being welcome to cast votes.

TODO link to recent votes as examples

Once the Incubator PMC votes to establish the podling, its infrastructure can be set up.

Usually, the Champion or incubation mentors drive this process. However, it can also be driven by podling community members if they know how to proceed.

See Infra and the Incubator for detailed instructions.

The project can not issue press releases or other public statements about joining the ASF before the Incubator PMC accepts the podling.

There are also some restrictions about how podlings can advertise themselves and especially around press releases related to podlings. The Incubator Branding Guide and Apache Podling Publicity/Media Guidelines have more details.

A specific process exists to donate code to the ASF, which podlings also need to follow, based on Software Grants and/or CCLAs.

The Initial Code Import guide has more details about this.

During incubation, the podling is expected to build and expand its community, which includes voting in new committers and PPMC members.

Discussions of candidates and votes happen on the podling’s private PPMC mailing list. That’s one of the few uses of that list as, generally, all discussions happen in the open.

Expanding and especially renewing project communities are essential parts of the ASF’s governance, as they foster project durability.

During incubation, we expect a podling to make several software releases that gradually progress towards being fully conformant to the ASF Release Policy. Producing fully-conformant releases is a condition for graduation.

Podling releases must also include the word "incubating" in any release file names and include a DISCLAIMER or DISCLAIMER-WIP as per the Incubator Releases Guide, to prevent any confusion as to the project’s status. As podlings are not yet "real" ASF projects, it is important to set expectations appropriately.

Note that Apache Releases consist of source code only. However, it is common for our projects to also distribute compiled packages along with their releases, as a convenience to users of the application. The focus is on the actual source code releases, and all distributed compiled packages are based on those "official" releases.

Voting on podling releases happens in two phases:

Many committers in podlings use several names when communicating with the project: their real name, their nickname, their github id, and their ASF id. When voting on releases, in order to make it clear who is voting, it is best practice to add your ASF id and your role(s) to your vote email. For example, if you are in the podling’s PPMC and also in the Incubator PMC, you can annotate your vote:

+1 clr (PPMC) (IPMC)

Voting in this way also makes it easier to tally the two phase votes.

Report votes from the podling dev list to the Incubator PMC vote in the Incubator PMC [VOTE] message, by explicitly mentioning the podling vote result and including a lists.apache.org link to the podling vote tally. This allows votes from mentors and other Incubator PMC members to be binding in the Incubator PMC vote, without people having to vote twice.

Both the podling and Incubator votes follow the standard ASF voting principles: they are majority votes that last at least 72 hours, and if people vote several times only their last vote counts.

Top-level projects (TLPs) are full-blown ASF projects, each governed by their own PMC and reporting to the ASF’s Board of Directors.

Podlings are "TLPs in training". Most of what they do is the same as TLPs, especially as they progress in their incubation journey.

The main differences are:

The ASF strongly encourages projects to grow and renew their roster regularly, to foster project sustainability. Both podlings and TLPs should be actively looking to elect new committers and PMC members by keeping an eye on who’s active in their communities.

Once the podling community starts feeling ready to graduate, they should make a self-assessment of that readiness.

The Maturity Model maintained by the ASF’s Community Development PMC is a good canvas for that and can help the podling community discover things that might have been overlooked during incubation. The Maturity Model page includes links to examples from graduate podlings.

Once the community and its incubation mentors feel that the podling is ready to graduate, based on their readiness self-assessment, a mentor or a member of the PPMC starts a [DISCUSS] thread on the Incubator general email list, proposing graduation and asking the Incubator PMC to review the podling.

It’s best to include the graduation resolution in this discussion, to be ready for the vote that follows.

If the people or organizations that donated the podling code to the ASF own trademarks that the podling needs, they must transfer the trademarks to the ASF before the podling can graduate.

TODO link to details

Once the discussion dies down on the graduation proposal, a mentor or a member of the PPMC starts a [VOTE] thread on the Incubator general mailing list, in which Incubator PMC Members cast their votes whether to recommend graduation to the ASF’s Board of Directors.

This vote follows the standard ASF voting principles. It’s a majority vote that lasts at least 72 hours, and if people vote several times only their last vote counts.

Once the Incubator PMC votes to graduate a podling, the IPMC sends the Board Resolution that was created for the vote to the ASF’s Board of Directors.

The Board currently meets on the third Wednesday of every month and votes on such resolutions during a regular meeting.

The Board vote is effective immediately, although the public minutes of the Board meeting appear later, usually within a month.

Once graduated, the podling needs to reflect its new status on the Incubator status pages and make a few changes to its resources and processes.

The Life after Graduation guide lists the corresponding tasks.