docs/155513: New chapter for Committer's Guide: Mentor Guidelines from portmgr
Chris Rees
utisoft at gmail.com
Sun Mar 13 09:10:08 UTC 2011
>Number: 155513
>Category: docs
>Synopsis: New chapter for Committer's Guide: Mentor Guidelines from portmgr
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Sun Mar 13 09:10:07 UTC 2011
>Closed-Date:
>Last-Modified:
>Originator: Chris Rees
>Release: FreeBSD 8.2-RELEASE i386
>Organization:
>Environment:
System: FreeBSD zeus.bayofrum.net 8.2-RELEASE FreeBSD 8.2-RELEASE #1: Sun Feb 27 22:19:51 UTC 2011 root at zeus.bayofrum.net:/usr/obj/usr/src/sys/ZEUS i386
>Description:
- SGMLise Mentor/Mentee Guidelines and add to Committer's Guide.
Proposed by: tabthorpe
Submitted by: Chris Rees (utisoft_at_gmail.com)
>How-To-Repeat:
>Fix:
The SMGL is rendered at:
http://www.bayofrum.net/~crees/comm.html#MENTOR.GUIDELINES
--- mentor_mentee_guidelines.diff begins here ---
Index: article.sgml
===================================================================
RCS file: /exports/cvsroot-freebsd/doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v
retrieving revision 1.293
diff -u -r1.293 article.sgml
--- article.sgml 22 Feb 2011 10:27:25 -0000 1.293
+++ article.sgml 13 Mar 2011 08:26:11 -0000
@@ -1230,6 +1230,216 @@
</sect2>
</sect1>
+ <sect1 id="mentor.guidelines">
+ <title>Guideline for Mentor/Mentee relationships</title>
+
+ <para>This section is intended to help demystify the
+ mentoring process, as well as a way to openly promote a
+ constructive discussion to adapt and grow the guidelines.
+ In our lives we have too many rules; we are not a
+ government organisation that inflicts regulation,
+ but rather a collective of like minded individuals
+ working toward a common goal, maintaining the quality
+ assurance of the product we call the Ports Tree.</para>
+
+ <sect2 id="why.mentor">
+ <title>Why mentor?</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>For most of us, we were mentored into the
+ Project, so return the favor by offering to mentor
+ somebody else in.</para>
+ </listitem>
+
+ <listitem>
+ <para>You have an irresistible urge to inflict knowledge
+ on others.</para>
+ </listitem>
+
+ <listitem>
+ <para>The usual punishment applies because you are sick and
+ tired of committing somebody else's good work!</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="mentor.comentor">
+ <title>Mentor/Co-Mentor</title>
+
+ <para>Reasons for a co-mentorship:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Significant timezone differential.
+ Accessible, interactive mentor(s) available via
+ IM is extremely helpful!</para>
+ </listitem>
+
+ <listitem>
+ <para>Potential language barrier. Yes, &os; is very
+ English oriented, as is most software development,
+ however, having a mentor who can speak a native language
+ can be very useful.</para>
+ </listitem>
+
+ <listitem>
+ <para>ENOTIME! Until there is a 30 hour day, and an 8 day
+ week, some of us only have so much time to give.
+ Sharing the load with somebody else will make
+ it easier.</para>
+ </listitem>
+
+ <listitem>
+ <para>A rookie mentor can benefit from the experience of a
+ senior committer/mentor.</para>
+ </listitem>
+
+ <listitem>
+ <para>Two heads are better than one.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Reasons for sole mentorship:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>You do not play nicely with others.</para>
+ </listitem>
+
+ <listitem>
+ <para>You prefer to have a one-on-one relationship.</para>
+ </listitem>
+
+ <listitem>
+ <para>The reasons for co-mentorship do not apply
+ to you.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="mentor.expectations">
+ <title>Expectations</title>
+
+ <para>We expect mentors to review and test-build all proposed
+ patches, at least for an initial period lasting more than a
+ week or two.</para>
+
+ <para>We expect that mentors should take responsibility for
+ the actions of their mentee. A mentor should follow up with
+ all commits the mentee makes, both approved
+ and implicit.</para>
+
+ <para>We expect mentors to make sure their mentees read the
+ <ulink url="&url.books.porters-handbook;">Porter's Handbook</ulink>,
+ the <ulink url="&url.articles.pr-guidelines">PR handling guide</ulink>,
+ and the <link linkend="admin">Committer's Guide</link>. While
+ it's not necessary to memorize all the details, every committer
+ needs to have an overview of these things to be an effective part
+ of the community (and avoid as many rookie mistakes as
+ possible.)</para>
+ </sect2>
+
+ <sect2 id="mentees">
+ <title>Selecting a mentee</title>
+
+ <para>There is no defined rule for what makes a candidate ready; it can be
+ a combination of number of PRs they have
+ submitted to <application>GNATS</application>, the number
+ of ports maintained, frequency of ports updates and/or level of
+ participation in a particular area of interest, e.g.
+ <application>GNOME</application>, <application>KDE</application>,
+ <application>Gecko</application> or others.</para>
+
+ <para>A candidate should have almost no timeouts, be responsive to requests,
+ and generally helpful in supporting their ports.</para>
+
+ <para>There must be a history of commitment, as it is widely understood
+ that training a committer requires time and effort.
+ If somebody has been around longer, and spent the time observing how
+ things are done, there is some anticipation of accumulated knowledge.
+ All too often we have seen a maintainer submit a few PRs, show up in
+ IRC and ask when they will be given a commit bit.</para>
+
+ <para>Being subscribed to, and following the mailing lists is very
+ beneficial. There is no real expectation that submitting posts on
+ the lists will make somebody a committer, but it demonstrates a
+ commitment. Some mails offer insights into the knowledge of a
+ candidate as well how they interact with others.
+ Similarly participating in IRC can give somebody a
+ higher profile.</para>
+
+ <para>Ask six different committers how many PRs a maintainer should submit
+ prior to being nominated, and you will get six different answers. Ask
+ those same individuals how long somebody should have been participating,
+ same dilemma. How many ports should they have at a minimum? Now we have
+ a bikeshed! Some things are just hard to quantify, a mentor will just
+ have to use their best judgement, and hope that
+ portmgr agrees.</para>
+
+ </sect2>
+ <sect2 id="mentorship.duration">
+ <title>Mentorship duration</title>
+
+ <para>As the trust level develops and grows, the mentee may be granted
+ <quote>implicits</quote> commit rights. This can include trivial
+ changes to a <filename>Makefile</filename>,
+ <filename>pkg-descr</filename> etc. Similarly, it may include
+ <makevar>PORTVERSION</makevar> updates that do not include
+ <makevar>plist</makevar> changes. Other circumstances
+ may be formulated at the discretion of the Mentor. However, during the
+ period of mentorship, a port version bump that affects dependent ports
+ should be checked by a mentor.</para>
+
+ <para>Just as we are all varied individuals, each mentee has different learning
+ curves, time commitments, and other influencing factors that will
+ contribute to the time required before they can <quote>fly solo</quote>.
+ Empirically, a mentee should be observed for at least 3 months.
+ 90-100 commits is another target that a mentor could use before releasing
+ a mentee. Other factors to consider prior releasing a mentee are the
+ number of mistakes they may have made, QATs received etc.
+ If they are still making rookie mistakes, they still
+ require mentor guidance.</para>
+ </sect2>
+
+ <sect2 id="mentor.comentor.debate">
+ <title>Mentor/Co-Mentor debate</title>
+
+ <para>When a request gets to portmgr, it usually reads as,
+ <quote>I propose 'foo' for a ports commit bit, I will co-mentor with
+ 'bar'</quote>. Proposal received, voted, and carried.</para>
+
+ <para>The mentor is the primary point of contact or the
+ <quote>first among equals</quote>, the co-mentor is the backup.</para>
+
+ <para>Some reprobate, whose name shall be withheld, made the
+ <ulink url="http://lists.freebsd.org/pipermail/cvs-ports/2007-September/134614.html">
+ first recorded co-mentor commit</ulink>.
+ Similar co-mentor commits have also been spotted in
+ the src tree. Does this make it right? Does this make it wrong?
+ It seems to be part of the evolution of how things are done.</para>
+ </sect2>
+
+ <sect2 id="mentee.expectations">
+ <title>Expectations</title>
+
+ <para>We expect mentees to be prepared for constructive criticism from the
+ community. There's still a lot of <quote>lore</quote> that isn't
+ written down. Responding well to constructive criticism is what we
+ hope we are selecting for by first reviewing their existing
+ contributions on IRC and mailing lists.</para>
+
+ <para>We warn mentees that some of the criticism they receive may be
+ less <quote>constructive</quote> than others, (whether through
+ language communication problems, or excessive nit-picking), and that
+ dealing with this gracefully is just part of being in a large community.
+ In case of specific problems with specific people, or any questions, we
+ hope that they will approach a portmgr member
+ on IRC or by email.</para>
+
+ </sect2>
+ </sect1>
+
<sect1 id="pref-license">
<title>Preferred License for New Files</title>
--- mentor_mentee_guidelines.diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list