doc/en_US.ISO8859-1/articles/port-mentor-guidelines/article.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
	"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:lang="en">
  <info>
    <title>Port Mentor Guidelines</title>

    <authorgroup>
      <author>
	<orgname>The &os; Ports Management Team</orgname>
      </author>
    </authorgroup>

    <pubdate>$FreeBSD$</pubdate>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <copyright>
      <year>2011</year>
      <holder role="mailto:tabthorpe@FreeBSD.org">Thomas
	Abthorpe</holder>
      <holder role="mailto:crees@FreeBSD.org">Chris Rees</holder>
    </copyright>
  </info>

  <sect1 xml:id="port-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 organization 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 xml: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 xml: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 xml: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
	<link xlink:href="&url.books.porters-handbook;">Porter's
	  Handbook</link>, the <link
	  xlink:href="&url.articles.pr-guidelines;">PR handling
	  guide</link>, and the <link
	  xlink:href="&url.articles.committers-guide;">Committer's
	  Guide</link>.  While it is 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 xml: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,
	the number of ports
	maintained, frequency of ports updates and/or level of
	participation in a particular area of interest like
	<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 xml:id="mentorship.duration">
      <title>Mentorship Duration</title>

      <para>As the trust level develops and grows, the mentee may be
	granted <quote>implicit</quote> commit rights.  This can
	include trivial changes to a <filename>Makefile</filename>,
	<filename>pkg-descr</filename> etc.  Similarly, it may include
	<varname>PORTVERSION</varname> updates that do not include
	<varname>plist</varname> 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 xml: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
	<link
	  xlink:href="http://lists.freebsd.org/pipermail/cvs-ports/2007-September/134614.html">
	  first recorded co-mentor commit</link>.  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 xml: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 is not 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>
</article>