From chris@zeus.bayofrum.net  Sun Mar 13 09:03:23 2011
Return-Path: <chris@zeus.bayofrum.net>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 45A781065673
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 13 Mar 2011 09:03:23 +0000 (UTC)
	(envelope-from chris@zeus.bayofrum.net)
Received: from relay.pcl-ipout01.plus.net (relay.pcl-ipout01.plus.net [212.159.7.99])
	by mx1.freebsd.org (Postfix) with ESMTP id 9C1A18FC18
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 13 Mar 2011 09:03:22 +0000 (UTC)
Received: from outmx02.plus.net ([212.159.14.17])
  by relay.pcl-ipout01.plus.net with ESMTP; 13 Mar 2011 08:33:51 +0000
Received: from 237.88.113.87.dyn.plus.net ([87.113.88.237] helo=zeus.bayofrum.net)
	 by outmx02.plus.net with esmtp (Exim) id 1PygkF-0002Al-Tr
	for FreeBSD-gnats-submit@freebsd.org; Sun, 13 Mar 2011 08:33:51 +0000
Received: from zeus.bayofrum.net (crees@localhost [127.0.0.1])
	by zeus.bayofrum.net (8.14.4/8.14.4) with ESMTP id p2D8XGIB027931
	(version=TLSv1/SSLv3 cipher=DHE-DSS-AES256-SHA bits=256 verify=NO)
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 13 Mar 2011 08:33:17 GMT
	(envelope-from chris@zeus.bayofrum.net)
Received: (from crees@localhost)
	by zeus.bayofrum.net (8.14.4/8.14.4/Submit) id p2D8XFEW027930;
	Sun, 13 Mar 2011 08:33:15 GMT
	(envelope-from chris)
Message-Id: <201103130833.p2D8XFEW027930@zeus.bayofrum.net>
Date: Sun, 13 Mar 2011 08:33:15 GMT
From: Chris Rees <utisoft@gmail.com>
Reply-To: Chris Rees <utisoft@gmail.com>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: New chapter for Committer's Guide: Mentor Guidelines from portmgr
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         155513
>Category:       docs
>Synopsis:       New chapter for Committer's Guide: Mentor Guidelines from portmgr
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    tabthorpe
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sun Mar 13 09:10:07 UTC 2011
>Closed-Date:    Wed Jul 20 17:51:23 UTC 2011
>Last-Modified:  Wed Jul 20 18:00:17 UTC 2011
>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@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:
Responsible-Changed-From-To: freebsd-doc->tabthorpe 
Responsible-Changed-By: tabthorpe 
Responsible-Changed-When: Mon Mar 14 03:18:09 UTC 2011 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=155513 


From: Thomas Abthorpe <tabthorpe@FreeBSD.org>
To: bug-followup@FreeBSD.org, utisoft@gmail.com
Cc:  
Subject: Re: docs/155513: New chapter for Committer's Guide: Mentor
 Guidelines from portmgr
Date: Wed, 11 May 2011 23:01:48 -0400

 Try this again, sans gpg signing, please look at
 http://people.freebsd.org/~tabthorpe/mentor-guidelines/
 
 -- 
 Thomas Abthorpe		| FreeBSD Committer
 tabthorpe@FreeBSD.org	| http://people.freebsd.org/~tabthorpe

From: Chris Rees <crees@freebsd.org>
To: bug-followup@freebsd.org
Cc:  
Subject: Re: docs/155513: New chapter for Committer's Guide: Mentor Guidelines
 from portmgr
Date: Sat, 25 Jun 2011 11:48:14 +0100

 Aha, sorry, consider your standalone article approved. I remember
 talking on IRC about it, but don't remember whether I said 'yes'!
 
 Chris
State-Changed-From-To: open->closed 
State-Changed-By: tabthorpe 
State-Changed-When: Wed Jul 20 17:51:22 UTC 2011 
State-Changed-Why:  
Committed, with minor changes. Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=155513 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/155513: commit references a PR
Date: Wed, 20 Jul 2011 17:50:49 +0000 (UTC)

 tabthorpe    2011-07-20 17:50:26 UTC
 
   FreeBSD doc repository (ports committer)
 
   Modified files:
     en_US.ISO8859-1/articles Makefile 
   Added files:
     en_US.ISO8859-1/articles/port-mentor-guidelines Makefile 
                                                     article.sgml 
   Log:
   Add guidelines for ports mentoring as an article.
   
   PR:             docs/155513 (based on)
   Submitted by:   crees
   Reviewed by:    rene
   
   Revision  Changes    Path
   1.63      +1 -0      doc/en_US.ISO8859-1/articles/Makefile
   1.1       +18 -0     doc/en_US.ISO8859-1/articles/port-mentor-guidelines/Makefile (new)
   1.1       +234 -0    doc/en_US.ISO8859-1/articles/port-mentor-guidelines/article.sgml (new)
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
>Unformatted:
