Document mentorships

Establishing mentorships is part of a proposal from Google to foster a
better collaboration within the Gerrit community (see change
I27e432cce).

In the past common issues with contributing large features have been:

* lack of reviews (because no maintainer can take the time that is
  required to do a thorough review)
* lack of quality (due to missing technical guidance)
* late rejection (after the implementation was already done and uploaded
  for code review)

These issues should be addressed by offering mentorship.

A mentor helps with:

* doing timely reviews
* providing technical guidance during code reviews
* discussing details of the design
* ensuring that the quality standards are met (well documented,
  sufficient test coverage, backwards compatible etc.)

Contributors can gain a mentorship if:

* the design for the feature has been approved
* the contributor is committed to do the implementation

Mentors are assigned by the steering committee.

The pool of mentors is formed by Gerrit maintainers and contributors
that volunteer to serve as mentor. Google is committed to fund 1-2
mentorships at a time, also for features that are not on Google's
roadmap. Everyone else in community is welcome to serve as mentor too.
It's also possible to only volunteer as mentor for specific features
(e.g. features of interest that are upcoming).

Google would be happy to get non-Google mentors for features that are
done by Google.

Mentors may not be available immediately. In this case, the steering
committee should include the approved feature into the roadmap or
prioritize it in the backlog. This way, it is transparent for the
contributor when they can expect to be able to work on the feature with
mentor support.

Change-Id: I10fa8e92639f3a00d7890f75180c6a93eb2a6f6d
Signed-off-by: Edwin Kempin <ekempin@google.com>

Documentation/dev-community.txt

@@ -19,6 +19,7 @@ link:dev-cla.html[contributor's agreement] on file with the project.
 ** link:dev-contributing.html#contribution-processes[Contribution Processes]
 *** link:dev-contributing.html#lightweight-contribution-process[Lightweight Contribution Process]
 *** link:dev-contributing.html#design-driven-contribution-process[Design-Driven Contribution Process]
+*** link:dev-contributing.html#mentorship[Mentorship]
 ** link:dev-design-docs.html#review[Design doc reviews]
 ** link:dev-processes.html#dev-in-stable-branches[Development in stable branches]
 ** link:dev-processes.html#backporting[Backporting to stable branches]
@@ -28,6 +29,7 @@ link:dev-cla.html[contributor's agreement] on file with the project.
 ** link:dev-roles.html#supporter[Supporter]
 ** link:dev-roles.html#contributor[Contributor]
 ** link:dev-roles.html#maintainer[Maintainer]
+** link:dev-roles.html#mentor[Mentor]
 ** link:dev-roles.html#steering-committee-member[Steering Committee Member]
 ** link:dev-roles.html#release-manager[Release Manager]
 
@@ -37,6 +39,7 @@ link:dev-cla.html[contributor's agreement] on file with the project.
 * link:dev-contributing.html#contribution-processes[Contribution Processes]
 ** link:dev-contributing.html#lightweight-contribution-process[Lightweight Contribution Process]
 ** link:dev-contributing.html#design-driven-contribution-process[Design-Driven Contribution Process]
+** link:dev-contributing.html#mentorship[Mentorship]
 * link:dev-design-docs.html[Design Docs]
 * link:dev-readme.html[Developer Setup]
 * link:https://gerrit.googlesource.com/gerrit/+/master/polygerrit-ui[Polymer Frontend Developer Setup]

Documentation/dev-contributing.txt

@@ -41,6 +41,14 @@ the Gerrit project, including link:dev-roles.html#maintainer[
 maintainers]. When reading this document, keep in mind that maintainers
 are also contributors when they contribute code.
 
+If a new feature is large or complex, it is often difficult to find a
+maintainer who can take the time that is needed for a thorough review,
+and who can help with getting the changes submitted. To avoid that this
+results in unpredictable long waiting times during code review,
+contributors can ask for link:#mentorship[mentor support]. A mentor
+helps with timely code reviews and technical guidance. Doing the
+implementation is still the responsibility of the contributor.
+
 [[comparison]]
 === Quick Comparison
 
@@ -50,11 +58,14 @@ are also contributors when they contribute code.
 |Overhead|low (write good commit message, address review comments)|
 high (write link:dev-design-docs.html[design doc] and get it approved)
 |Technical Guidance|by reviewer|during the design review and by
-reviewer
+reviewer/mentor
+|Review  |adhoc (when reviewer is available)|by a dedicated mentor (if
+a link:#mentorship[mentor] was assigned)
 |Caveats |features may get vetoed after the implementation was already
 done, maintainers may make the design-driven contribution process
 required if a change gets too complex/large|design doc must stay open
-for a minimum of 10 calendar days
+for a minimum of 10 calendar days, a mentor may not be available
+immediately
 |Applicable to|documentation updates, bug fixes, small features|
 large/complex features
 |======================
@@ -157,6 +168,8 @@ while the design wasn't approved yet.
 By approving a design, the steering committee commits to:
 
 * Accepting the feature when it is implemented.
+* Supporting the feature by assigning a link:dev-roles.html#mentor[
+  mentor] (if requested, see link:#mentorship[mentorship]).
 
 If the implementation of a feature gets stuck and it's unclear whether
 the feature gets fully done, it should be discussed with the steering
@@ -177,6 +190,59 @@ following advantages:
   Hence, there is only a low risk to invest into implementing a feature
   and see it being rejected later during the code review, as it can
   happen with the lightweight contribution process.
+* The contributor can link:#mentorship[get a dedicated mentor assigned]
+  who provides timely reviews and serves as a contact person for
+  technical questions and discussing details of the design.
+
+[[mentorship]]
+== Mentorship
+
+For features for which a link:dev-design-docs.html[design] has been
+approved (see link:#design-driven-contribution-process[design-driven
+contribution process]), contributors can gain the support of a mentor
+if they are committed to implement the feature.
+
+A link:dev-roles.html#mentor[mentor] helps with:
+
+* doing timely reviews
+* providing technical guidance during code reviews
+* discussing details of the design
+* ensuring that the quality standards are met (well documented,
+  sufficient test coverage, backwards compatible etc.)
+
+A feature can have more than one mentor. To be able to deliver the
+promised support, at least one of the mentors must be a
+link:dev-roles.html#maintainer[maintainer].
+
+Mentors are assigned by the link:dev-processes.html#steering-committee[
+steering committee]. To gain a mentor, ask for a mentor in the
+link:dev-design-doc-template.html#implementation-plan[Implementation
+Plan] section of the design doc or ask the steering committee after the
+design has been approved.
+
+Mentors may not be available immediately. In this case, the steering
+committee should include the approved feature into the roadmap or
+prioritize it in the backlog. This way, it is transparent for the
+contributor when they can expect to be able to work on the feature with
+mentor support.
+
+Once the implementation phase starts, the contributor is expected to do
+the implementation in a timely manner.
+
+For every mentorship, the end must be clearly defined. The design doc
+must specify:
+
+* a maximum time frame for the mentorship, after which the mentorship
+  automatically ends, even if the feature is not done yet
+* done criteria that define when the feature is done and the mentorship
+  ends
+
+If a feature is not finished in time, it should be discussed with the
+steering committee how to proceed. If the contributor cannot commit to
+finish the implementation in time and no other contributor can take
+over, changes that have already been submitted for the feature might
+get reverted so that there is no unused or half-finished code in the
+code base.
 
 GERRIT
 ------

Documentation/dev-design-doc-template.txt

@@ -46,6 +46,31 @@ implementation is planned and which priority it has for you.
 It is possible to contribute designs without having resources to do the
 implementation. In this case, say so here.
 
+If mentor support is desired, say so here. Also briefly describe any
+circumstances that can help with finding a suitable mentor.
+
+[[time-estimation]]
+=== Time Estimation
+
+A rough itemized estimation of how much time it takes to implement this
+feature. Break down the feature into work items and estimate each item
+separately.
+
+If a mentor is assigned, this section must define a maximum time frame
+after which the mentorship automatically ends even if the feature isn't
+fully done yet.
+
+[[done-criteria]]
+== Done Criteria
+
+Describe the conditions that must be satisfied to consider this feature
+as done.
+
+If a mentor is assigned, the mentorship ends when this state is reached.
+Please note that a mentorship can also end earlier if the maximum time
+frame for the mentorship has exceeded (see section 'Time Estimation'
+above).
+
 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]

Documentation/dev-processes.txt

@@ -15,6 +15,7 @@ The Gerrit project has a steering committee that is in charge of:
   link:dev-design-docs.html[design docs] within 14 calendar days)
 * approving/rejecting link:dev-design-docs.html[designs], vetoing new
   features
+* assigning link:dev-roles.html#mentor[mentors] for approved features
 * accepting new plugins as core plugins
 * making changes to the project governance process and the
   link:dev-contributing.html#contribution-processes[contribution

Documentation/dev-roles.txt

@@ -117,7 +117,9 @@ permissions (see link:#supporter[supporter] section above).
 
 It's highly appreciated if contributors engage in code reviews,
 link:dev-design-docs.html#review[design reviews] and mailing list
-discussions.
+discussions. If wanted, contributors can also serve as link#mentor[
+mentors] to support other contributors with getting their features
+done.
 
 Contributors may also be invited to join the Gerrit hackathons which
 happen regularly (e.g. twice a year). Hackathons are announced on the
@@ -165,6 +167,7 @@ following tasks (but are not required to do so):
   design-driven contribution process] by reviewing incoming
   link:dev-design-docs.html[design docs] and raising concerns during
   the design review
+* serving as link:#mentor[mentor]
 * doing releases (see link#release-manager[release manager])
 
 Maintainers can:
@@ -238,6 +241,34 @@ link:#maintainer[Maintainers] can become steering committee member by
 election, or by being appointed by Google (only for the seats that
 belong to Google).
 
+[[mentor]]
+== Mentor
+
+A mentor is a link:#maintainer[maintainer] or link:#contributor[
+contributor] who is assigned to support the development of a feature
+that was specified in a link:dev-design-docs.html[design doc] and was
+approved by the link:dev-processes.html#steering-committee[steering
+committee].
+
+The goal of the mentor is to make the feature successful by:
+
+* doing timely reviews
+* providing technical guidance during code reviews
+* discussing details of the design
+* ensuring that the quality standards are met (well documented,
+  sufficient test coverage, backwards compatible etc.)
+
+The implementation is fully done by the contributor, but optionally
+mentors can help out with contributing some changes.
+
+link:#maintainer[Maintainers] and link:#contributor[contributors] can
+volunteer to generally serve as mentors, or to mentor specific features
+(e.g. if they see an upcoming feature on the roadmap that they are
+interested in). To volunteer as mentor, contact the
+link:dev-processes.html#steering-committee[steering committee] or
+comment on a change that adds a link:dev-design-docs.html#propose[
+design doc].
+
 [[release-manager]]
 == Release Manager