Estimated Reading Time:

The Mentors' guide is a go-to place for information about getting a podling up and running from an infrastructure point of view.

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 Responsibilitiesdocument.

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.

Overview

After the Podling has been accepted by the Incubator PMC, one of the mentors sets up the Podling; i.e. adds the podling metadata, creates the initial Podling status page, and either creates or requests that other resources (mail lists, subversion, bug tracker, etc.) be created.

Add to Incubation Summary file

Add the podling to the podling summary file in the "incubator" SVN at content/podlings.xml (e.g. copy the entry from another podling that also has status="current") and see instructions.

Please do this step ASAP after Acceptance. Other setup procedures utilize this metadata.

Add a 'reporting' tag (after 'description') with the attribute 'monthly="true"' and the appropriate "group" attribute, based on the month in which the podling entered incubation (1 for January, April, July, October, 2 for February, May, August, November or 3 for March, June, September, December). The text content of the 'reporting' tag must contain the initial list of reporting months, starting with the month after the podling entered incubation. Below is an example of the final XML snippet

    <podling name="PodlingName" status="current" resource="podlingname" sponsor="Sponsor" startdate="YYYY-MM-DD">
        <description>A description of the podling, for the status page and reports</description>
        <reporting group="1|2|3" monthly="true">First,Second,Third</reporting>
        <champion availid="userid">Champion Name</champion>
        <mentors>
            <mentor username="userid">Mentor One</mentor>
            <mentor username="userid">Mentor Two</mentor>
            <mentor username="userid">Mentor Three</mentor>
        </mentors>
    </podling>

An example reporting block:

<reporting group="3" monthly="true">June, July, August</reporting>

Once the first three reports are complete, the monthly attribute should be removed and the list of months removed as well.

The first report might be very short. However it is better that the Incubator PMC can help to guide through the early setup stages. For more details see the PPMC Guide.

Initialize Podling Status Page

A mentor needs to create the web page that will track the project’s status. A mentor will also need to update it until others in the project’s PPMC can update it.

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.

Resources

Resources should be requested in a particular order, and based on paperwork processed. Do not request source repositories before SGAs are filed, for instance.

Request Required Resources

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.

Request Mailing 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 link:https://infra.apache.org/officers/mlreq/incubator" target="_new[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 link:https://lists.apache.org" target="_new[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

Request an issue tracker on the infra service desk

Remember to post an email announcing that the issue tracker is available.

[DRAFT] Podling Bootstrap

NOTE This section is a DRAFT under development.

Following podling creation, it needs to be bootstrapped. Here are some of the tasks:

Mentors MUST be on the IPMC

Mentors MUST be on the IPMC. This should be checked prior to beginning incubation. 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.