pages/guides/mentor.ad - incubator - Git at Google

 //Licensed under the Apache License, Version 2.0 (the "License");
 //you may not use this file except in compliance with the License.
 //You may obtain a copy of the License at
 //
 //http://www.apache.org/licenses/LICENSE-2.0
 //
 //Unless required by applicable law or agreed to in writing, software
 //distributed under the License is distributed on an "AS IS" BASIS,
 //WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 //See the License for the specific language governing permissions and
 //limitations under the License.
 = Mentors' Guide
 Apache Incubator PMC
 2002-10-16
 :jbake-type: pmcGuide
 :jbake-status: published
 :idprefix:
 :toc:
 :imagesdir: ../images/

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

 This document is for 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
 link:/guides/roles_and_responsibilities.html#Mentor[Roles and Responsibilities]document.

 This guide describes established practices.
 It is informational, not normative. Policy is in the
 link:/incubation/Incubation_Policy.html[Incubation Policy] document.

 == Overview

 After the Incubator PMC (IPMC) has accepted a podling, one of the mentors
 link:/incubation/Incubation_Policy.html#Setting+Up+a+New+Podling[sets it up]: adds the podling metadata, creates the initial podling status page, and
 either creates
 other resources (such as email lists, Git or Subversion code repository, bug tracker, and wiki) or requests that the others involved with the IPMC or the Infrastructure team create them.

 == Add to the Incubation Summary file

 Add the podling to the podling summary file in
 the "incubator" SVN at *content/podlings.xml*
 (copy and modify the entry for another podling that has status="current"). See the link:website.html[instructions].

 Do this step as soon as possible after Acceptance. Other setup procedures use
 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:

 [literal]
 ----
     <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:
 [literal]
 ----
 <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
 link:ppmc.html#Incubator+ASF+Board+Reports[PPMC Guide].

 == Initialize the Podling Status Page

 A mentor needs to
 link:website.html#Edit+your+project+status+page[create the web page] to track the project's status.
 A mentor will also need to update it until
 link:ppmc.html#Project+Status+Updates[others in the project's PPMC can update it].

 The status
 page is the Incubator's record of the progress the project makes.
 The mentor or the PPMC MUST keep it up to date during incubation.
 Some of the information for the page is available from the podling proposal.
 As the startup process continues and the project creates resources, the PPMC SHOULD update the web page.

 The template contains lists of actions which you need to perform
 to start up a podling. Delete all actions which do not apply to the podling you are initializing.

 The status page is a useful aid to workflow. Volunteers
 can use it to sign up to various tasks and monitor their
 progress. Once the mailing lists are set up and prospective
 committers subscribe, use the dev@ list for task discussion.

 == Resources

 You need to request resources in a particular order, based on paperwork processed. Do not request source repositories before SGAs are filed, for instance, if the source code is not already Apache licensed or Category A licensed.

 The proposal should include a list of required resources. All resources require active set-up. The Infra team creates some after an appropriate
 request; IPMC members (typically mentors) can set others up.

 Infra has a guide, link:https://infra.apache.org/infra-incubator.html[Infra and the Incubator], to help you understand the flow of resource requests, and to guide you in requesting resources.

 The first resources you need to create are LDAP and DNS.  Request them from Infra via link:https://issues.apache.org/jira/browse/INFRA[Apache Infra Jira -> Create Task].

 Once these items are available, create the mailing lists. Other resources typically post information to these lists.

 === Request Email Lists

 Apache email lists require volunteer moderators. New moderators can be
 link:http://www.apache.org/dev/committers.html#mailing-list-moderators[added later]
 but at least one volunteer is required before you can set up the email lists.
 Moderation is a reasonably
 link:http://www.apache.org/dev/committers.html#mail-moderate[easy task],
 though moderators may want to set up
 link:http://spamassassin.apache.org/[spam filtering].
 We recommend that each podling have at least three moderators to spread the load.

 The proposal should contain the rest of the information that you need to request the email lists. 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 when community size and activity require it.  A podling that is already established and using an existing user interaction channel may want to keep those resources around until they feel they have transitioned to the ASF successfully.  Discuss this on your existing development lists.

 [NOTE]
 ====
 If you are using SVN,
 commits under *http://svn.apache.org/repos/asf/incubator/_${podling}_* will be emailed to *commits@${podling}.incubator.apache.org*.
 Any deviation will require the IPMC to create a special configuration in the *asf-mailer.conf* file.
 ====

 Email list creation is a task for the link:#who-infra[Infrastructure team]. Infra offers a tool, the link:https://selfserve.apache.org/mail.html[Incubator Email List Request Form^], that simplifies the creation of email lists.  A notification will be sent to private@incubator when the lists have been created.

 Remember to update the project status file with email 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 active, 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 link:http://mail-archives.apache.org/mod_mbox/[http://mail-archives.apache.org/mod_mbox/] for the public
 email lists will be set up as part of the mailing list creation process. Mentors do not need to do anything. The archives will be link:http://mail-archives.apache.org/mod_mbox/[visible]
 as soon as posts have been made (and moderated) to these lists.

 You can also leverage link:https://lists.apache.org[lists.apache.org^] for
 email 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 project email lists are archived externally (for example, at
 link:http://www.mail-archive.com/[The Mail Archive] and
 link:http://marc.info/?q=about[MARC]).
 Independent archives help
 increase project visibility and preserve an independent historical record.
 We do not create these subscriptions automatically. If the project wants one, subscribe manually.

 You must also create subscriptions to news-to-mailing-list bridges (for example, link:http://www.nabble.com[Nabble])
 manually. Subscribing helps accessibility and visibility, but Nabble news
 users may not be aware that they are posting to an email list.

 ==== Email List Administration

 Apache uses link:http://www.ezmlm.org/[ezmlm]. See the
 link:http://www.ezmlm.org/man/ezmlmman.html[manual] and
 committer link:https://infra.apache.org/committers.html#mail[mail FAQ]
 for more details.

 ==== Email List Transition

 Independent email lists and groups are perfectly acceptable, but development-related discussions and decisions should
 happen on the official email lists at Apache. If a project has existing email lists,
 forums or groups, the community needs to consider their future and plan for the transition
 to the official Apache email lists.

 It may be useful to move development first to the official lists, followed gradually
 by the user resources.

 Note that subscribers of external email lists will not be automatically subscribed
 to the new Incubator project email lists. Instead, post a note to the
 old external email list asking participants to subscribe to the new list. If possible, add
 a footer to the old email list with some instructions.

 === Self Service Requests

 You can request most of the resources you will need via link:https://selfserve.apache.org/[Self Service]. This includes seeting up Git repositories, email lists, a project presence on Jira and project space on the Confluence Wiki.  If you do not have access to Self Serve, use link:https://issues.apache.org/jira/browse/INFRA[Jira] instead.

 ==== Jira Issue Tracking

 To request access to Jira, visit https://selfserve.apache.org/jira.html.

 ==== Other Issue Trackers

 Request an issue tracker on the link:https://issues.apache.org/jira/browse/INFRA[Infra Jira].

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

 === Git Migrations

 To request a Git migration, file a link:https://issues.apache.org/jira/browse/INFRA[New Git Repository] Infra ticket, requesting to migrate from an existing organization to the Apache organization.

 === Gitbox Requests

 To request Gitbox repositories for a new podling, first file a link:https://issues.apache.org/jira/browse/INFRA[GitBox Integration] Infra ticket.  Once your podling has been added, you can use link:https://gitbox.apache.org/ to manage your Gitbox repositories and user information.

 == Podling Bootstrap

 Following podling creation, you need to bootstrap it. Here are some of the tasks:

 * Ensure link:#mentors-ipmc[Mentors are on the IPMC]
 * Add the podling to the link:#Sending+in+an+Incubation+Report[reporting schedule]
 * link:#Initialize+Podling+Status+Page[Initialize the project status page]
 * Start link:#orientation[orientation] for link:#who-committers[prospective committers]
 * Start *CLA* and *CCLA* submissions link:#who-committers[for prospective committers]
 * Request Required Resources
 ** link:#request-mailing-lists[Email Lists]
 *** Consider and plan link:#transition-mailing-lists[transition to official email lists]
 *** Ensure all PPMC members sign up to the private email list
 ** link:#request-issue-tracking[Issue Tracking]
 *** Consider and plan link:#issue-tracking-transition[issue tracking transition]
 * link:#create-website[Create a website] with a page for link:#who-committers[prospective committers]
 ** Consider and plan link:#web-site-transition[web site transition]
 * Start link:#initial-ip-clearance[IP clearance]
 * Start *SGA* submission
 ** link:#Set+Up+Repository[Transfer repositories]

 == Mentors MUST be on the IPMC

 Mentors link:/policy/incubation.html#Mentor[MUST] be on the IPMC.  Verify this 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*.

 [NOTE]
 ====
 This process may take a few days.
 ====

 == CLA and CCLA Submission

 Prospective committers need to submit a Contributor License Agreement
 (link:http://www.apache.org/licenses/#clas[CLA]).
 This process can take a while, so we recommend that committers start to submit
 these as soon as the podling is accepted.
	//Licensed under the Apache License, Version 2.0 (the "License");
	//you may not use this file except in compliance with the License.
	//You may obtain a copy of the License at
	//
	//http://www.apache.org/licenses/LICENSE-2.0
	//
	//Unless required by applicable law or agreed to in writing, software
	//distributed under the License is distributed on an "AS IS" BASIS,
	//WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	//See the License for the specific language governing permissions and
	//limitations under the License.
	= Mentors' Guide
	Apache Incubator PMC
	2002-10-16
	:jbake-type: pmcGuide
	:jbake-status: published
	:idprefix:
	:toc:
	:imagesdir: ../images/

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

	This document is for 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
	link:/guides/roles_and_responsibilities.html#Mentor[Roles and Responsibilities]document.

	This guide describes established practices.
	It is informational, not normative. Policy is in the
	link:/incubation/Incubation_Policy.html[Incubation Policy] document.

	== Overview

	After the Incubator PMC (IPMC) has accepted a podling, one of the mentors
	link:/incubation/Incubation_Policy.html#Setting+Up+a+New+Podling[sets it up]: adds the podling metadata, creates the initial podling status page, and
	either creates
	other resources (such as email lists, Git or Subversion code repository, bug tracker, and wiki) or requests that the others involved with the IPMC or the Infrastructure team create them.

	== Add to the Incubation Summary file

	Add the podling to the podling summary file in
	the "incubator" SVN at content/podlings.xml
	(copy and modify the entry for another podling that has status="current"). See the link:website.html[instructions].

	Do this step as soon as possible after Acceptance. Other setup procedures use
	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:

	[literal]
	----
	<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:
	[literal]
	----
	<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
	link:ppmc.html#Incubator+ASF+Board+Reports[PPMC Guide].

	== Initialize the Podling Status Page

	A mentor needs to
	link:website.html#Edit+your+project+status+page[create the web page] to track the project's status.
	A mentor will also need to update it until
	link:ppmc.html#Project+Status+Updates[others in the project's PPMC can update it].

	The status
	page is the Incubator's record of the progress the project makes.
	The mentor or the PPMC MUST keep it up to date during incubation.
	Some of the information for the page is available from the podling proposal.
	As the startup process continues and the project creates resources, the PPMC SHOULD update the web page.

	The template contains lists of actions which you need to perform
	to start up a podling. Delete all actions which do not apply to the podling you are initializing.

	The status page is a useful aid to workflow. Volunteers
	can use it to sign up to various tasks and monitor their
	progress. Once the mailing lists are set up and prospective
	committers subscribe, use the dev@ list for task discussion.

	== Resources

	You need to request resources in a particular order, based on paperwork processed. Do not request source repositories before SGAs are filed, for instance, if the source code is not already Apache licensed or Category A licensed.

	The proposal should include a list of required resources. All resources require active set-up. The Infra team creates some after an appropriate
	request; IPMC members (typically mentors) can set others up.

	Infra has a guide, link:https://infra.apache.org/infra-incubator.html[Infra and the Incubator], to help you understand the flow of resource requests, and to guide you in requesting resources.

	The first resources you need to create are LDAP and DNS. Request them from Infra via link:https://issues.apache.org/jira/browse/INFRA[Apache Infra Jira -> Create Task].

	Once these items are available, create the mailing lists. Other resources typically post information to these lists.

	=== Request Email Lists

	Apache email lists require volunteer moderators. New moderators can be
	link:http://www.apache.org/dev/committers.html#mailing-list-moderators[added later]
	but at least one volunteer is required before you can set up the email lists.
	Moderation is a reasonably
	link:http://www.apache.org/dev/committers.html#mail-moderate[easy task],
	though moderators may want to set up
	link:http://spamassassin.apache.org/[spam filtering].
	We recommend that each podling have at least three moderators to spread the load.

	The proposal should contain the rest of the information that you need to request the email lists. 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 when community size and activity require it. A podling that is already established and using an existing user interaction channel may want to keep those resources around until they feel they have transitioned to the ASF successfully. Discuss this on your existing development lists.

	[NOTE]
	====
	If you are using SVN,
	commits under http://svn.apache.org/repos/asf/incubator/_${podling}_ will be emailed to commits@${podling}.incubator.apache.org.
	Any deviation will require the IPMC to create a special configuration in the asf-mailer.conf file.
	====

	Email list creation is a task for the link:#who-infra[Infrastructure team]. Infra offers a tool, the link:https://selfserve.apache.org/mail.html[Incubator Email List Request Form^], that simplifies the creation of email lists. A notification will be sent to private@incubator when the lists have been created.

	Remember to update the project status file with email 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 active, 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 link:http://mail-archives.apache.org/mod_mbox/[http://mail-archives.apache.org/mod_mbox/] for the public
	email lists will be set up as part of the mailing list creation process. Mentors do not need to do anything. The archives will be link:http://mail-archives.apache.org/mod_mbox/[visible]
	as soon as posts have been made (and moderated) to these lists.

	You can also leverage link:https://lists.apache.org[lists.apache.org^] for
	email 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 project email lists are archived externally (for example, at
	link:http://www.mail-archive.com/[The Mail Archive] and
	link:http://marc.info/?q=about[MARC]).
	Independent archives help
	increase project visibility and preserve an independent historical record.
	We do not create these subscriptions automatically. If the project wants one, subscribe manually.

	You must also create subscriptions to news-to-mailing-list bridges (for example, link:http://www.nabble.com[Nabble])
	manually. Subscribing helps accessibility and visibility, but Nabble news
	users may not be aware that they are posting to an email list.

	==== Email List Administration

	Apache uses link:http://www.ezmlm.org/[ezmlm]. See the
	link:http://www.ezmlm.org/man/ezmlmman.html[manual] and
	committer link:https://infra.apache.org/committers.html#mail[mail FAQ]
	for more details.

	==== Email List Transition

	Independent email lists and groups are perfectly acceptable, but development-related discussions and decisions should
	happen on the official email lists at Apache. If a project has existing email lists,
	forums or groups, the community needs to consider their future and plan for the transition
	to the official Apache email lists.

	It may be useful to move development first to the official lists, followed gradually
	by the user resources.

	Note that subscribers of external email lists will not be automatically subscribed
	to the new Incubator project email lists. Instead, post a note to the
	old external email list asking participants to subscribe to the new list. If possible, add
	a footer to the old email list with some instructions.

	=== Self Service Requests

	You can request most of the resources you will need via link:https://selfserve.apache.org/[Self Service]. This includes seeting up Git repositories, email lists, a project presence on Jira and project space on the Confluence Wiki. If you do not have access to Self Serve, use link:https://issues.apache.org/jira/browse/INFRA[Jira] instead.

	==== Jira Issue Tracking

	To request access to Jira, visit https://selfserve.apache.org/jira.html.

	==== Other Issue Trackers

	Request an issue tracker on the link:https://issues.apache.org/jira/browse/INFRA[Infra Jira].

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

	=== Git Migrations

	To request a Git migration, file a link:https://issues.apache.org/jira/browse/INFRA[New Git Repository] Infra ticket, requesting to migrate from an existing organization to the Apache organization.

	=== Gitbox Requests

	To request Gitbox repositories for a new podling, first file a link:https://issues.apache.org/jira/browse/INFRA[GitBox Integration] Infra ticket. Once your podling has been added, you can use link:https://gitbox.apache.org/ to manage your Gitbox repositories and user information.

	== Podling Bootstrap

	Following podling creation, you need to bootstrap it. Here are some of the tasks:

	* Ensure link:#mentors-ipmc[Mentors are on the IPMC]
	* Add the podling to the link:#Sending+in+an+Incubation+Report[reporting schedule]
	* link:#Initialize+Podling+Status+Page[Initialize the project status page]
	* Start link:#orientation[orientation] for link:#who-committers[prospective committers]
	* Start CLA and CCLA submissions link:#who-committers[for prospective committers]
	* Request Required Resources
	** link:#request-mailing-lists[Email Lists]
	*** Consider and plan link:#transition-mailing-lists[transition to official email lists]
	*** Ensure all PPMC members sign up to the private email list
	** link:#request-issue-tracking[Issue Tracking]
	*** Consider and plan link:#issue-tracking-transition[issue tracking transition]
	* link:#create-website[Create a website] with a page for link:#who-committers[prospective committers]
	** Consider and plan link:#web-site-transition[web site transition]
	* Start link:#initial-ip-clearance[IP clearance]
	* Start SGA submission
	** link:#Set+Up+Repository[Transfer repositories]

	== Mentors MUST be on the IPMC

	Mentors link:/policy/incubation.html#Mentor[MUST] be on the IPMC. Verify this 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.

	[NOTE]
	====
	This process may take a few days.
	====

	== CLA and CCLA Submission

	Prospective committers need to submit a Contributor License Agreement
	(link:http://www.apache.org/licenses/#clas[CLA]).
	This process can take a while, so we recommend that committers start to submit
	these as soon as the podling is accepted.