Merge pull request #86 from cottage14/patch-20
Update mentor.ad
diff --git a/pages/guides/mentor.ad b/pages/guides/mentor.ad
index 8986d23..8f8a14c 100644
--- a/pages/guides/mentor.ad
+++ b/pages/guides/mentor.ad
@@ -18,44 +18,40 @@
:toc:
:imagesdir: ../images/
-The Mentors' guide is a go-to place for information about getting a podling up and running from an infrastructure point of view.
+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 targets any Incubating Project member, but
+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 is a descriptive and at times
-discursive document. It describes established practices.
-It is informational not normative. Policy is laid down in the
-link:/incubation/Incubation_Policy.html[Incubation Policy].
+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 Podling has been accepted by the Incubator PMC, one of the mentors
-link:/incubation/Incubation_Policy.html#Setting+Up+a+New+Podling[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.
+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 Incubation Summary file
+== Add to the 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 link:website.html[instructions].
+(copy and modify the entry for another podling that has status="current"). See the link:website.html[instructions].
-Please do this step ASAP after Acceptance. Other setup procedures utilize
+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
+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
+starting with the month after the podling entered incubation. Below is an example of the final XML snippet:
[literal]
----
@@ -85,56 +81,52 @@
For more details see the
link:ppmc.html#Incubator+ASF+Board+Reports[PPMC Guide].
-== Initialize Podling Status Page
+== Initialize the Podling Status Page
A mentor needs to
-link:website.html#Edit+your+project+status+page[create the web page] that will track the project's status.
+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 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.
+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 may be needed
-to start up a podling. All those which do not apply should
-be deleted.
+The template contains lists of actions which you be need
+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 the various tasks and monitor their
+can use it to sign up to various tasks and monitor their
progress. Once the mailing lists are set up and prospective
-committers subscribe then these may be used for discussion.
+committers subscribe, use the dev@ list for task 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, if the source code is not already Apache licensed or Category A licensed.
+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 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).
+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 that you can use to understand the flow of resource requests, and should be used to guide you in requesting resources. link:https://infra.apache.org/infra-incubator.html[Infra and the Incubator]
+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 to be created are LDAP and DNS. These should be requested from Infra via link:https://issues.apache.org/jira/browse/INFRA[Apache Infra JIRA -> Create Task]
+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 requested, mailing lists should be created next. Other resources typically post information to these lists.
+Once these items are available, create the mailing lists. Other resources typically post information to these lists.
-=== Request Mailing Lists
+=== Request Email Lists
-Apache mailing lists require volunteer moderators. New moderators can be
-link:http://www.apache.org/dev/committers.html#mailing-list-moderators[changed later]
-but at least one volunteer is required before the mailing lists can be set up.
+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].
-Having at least three moderators is recommended to spread the load.
+We recommend that each podling have at least three moderators 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.
+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:
@@ -142,118 +134,114 @@
- 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. 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. You will want to discuss this on your existing development lists.
+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 requires 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 special configuration in the *asf-mailer.conf* file by the IPMC.
+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.
====
-Mailing lists creation is a task for the link:#who-infra[infrastructure team]. The
-infrastructure team offers a tool that simplifies the creation of mailing lists. You can access the
-link:https://selfserve.apache.org/mail.html[Incubator Mailing List Request Form^]
-to request a list. A notification will be sent to private@incubator when the lists have been created.
+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 mailing list details. Prospective committers
+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 created, the project MUST review
+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
-mailing lists will be setup as part of the mailing list creation process. No action is
-required by Mentors. The archives will be link:http://mail-archives.apache.org/mod_mbox/[visible]
+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
-mailing list archives. There is a login link in the top right corner, which allows you to respond to
+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 projects are independently archived externally (for example, at
+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 to
-increase project visibility as well as preserving a independent historic record.
-These subscriptions are not automatically created. If desired, subscribe manually.
+link:http://marc.info/?q=about[MARC]).
+Independent archives help
+increase project visibility and preserve an independent historic record.
+We do not create these subscriptions automatically. If the project wants one, subscribe manually.
-Subscriptions to news-to-mailing-list bridges (for example, link:http://www.nabble.com[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.
+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.
-==== Mailing List Administration
+==== 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:http://www.apache.org/dev/committers.html#mail[mail FAQ]
+committer link:https://infra.apache.org/committers.html#mail[mail FAQ]
for more details.
-==== Mailing List Transition
+==== Email 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,
+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 mailing lists.
+to the official Apache email lists.
-It may be useful to move development first to the official lists followed gradually
+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.
+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
-Most of the resources you will request can be done via Self Service. To do that, visit https://selfserve.apache.org/ and request the necessary resources. This includes git, mailing lists, JIRA and Confluence. If you do not have access to Self Serve, please use link:https://issues.apache.org/jira/browse/INFRA[JIRA] instead.
+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
+==== Jira Issue Tracking
-To request JIRA, visit https://selfserve.apache.org/jira.html
+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]
+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, please 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
+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, please 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.
+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, it needs to be bootstrapped. Here are some of the tasks:
+Following podling creation, you need to bootstrap it. Here are some of the tasks:
* Ensure link:#mentors-ipmc[Mentors are on the IPMC]
-* Add podling to link:#Sending+in+an+Incubation+Report[reporting schedule]
-* link:#Initialize+Podling+Status+Page[Initialize project status page]
-* Start link:#orientation[orientation] link:#who-committers[Prospective committers]
-* Start *CLA* and *CCLA* submission link:#who-committers[Prospective committers]
+* 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[Prospective committers]
* Request Required Resources
-** link:#request-mailing-lists[Mailing Lists]
-*** Consider and plan link:#transition-mailing-lists[transition to official mailing lists]
-*** Ensure all PPMC members are signed up to the private mailing list
+** 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 website] link:#who-committers[Prospective committers]
+* 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 link:#initial-ip-clearance[IP clearance]
* Start *SGA* submission
-** link:#Set+Up+Repository[Transfer Repos]
+** link:#Set+Up+Repository[Transfer repositories]
== Mentors MUST be on the IPMC
-Mentors link:/policy/incubation.html#Mentor[MUST] be on the IPMC. This should be checked prior to beginning incubation.
+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*.
@@ -266,5 +254,5 @@
Prospective committers need to submit a Contributor License Agreement
(link:http://www.apache.org/licenses/#clas[CLA]).
-This process can take a while so it is recommended that committers start to submit
+This process can take a while, so we recommend that committers start to submit
these as soon as the podling is accepted.
