Things all ports mentors and potential mentees should know

Tue Nov 30 15:08:40 UTC 2010

Greetings list

This document was initially prepared by portmgr@ as a means of
addressing issues around ports quality, in addition to informing
mentors/mentees their duties and obligations within the ports tree.

It has gone through some peer review among ports committers, integrating
feedback from the community at large.  This is intended as a living,
growing document to be updated and modified over time.  At some point
in the future, it will likely get rendered for use on the WWW, in the
meantime it is being tracked as a text file.

Without further delay, I would like to present Mentoring Guidelines,
feedback welcome!

Guideline for Mentor/Mentee relationships
=========================================

"The code is more what you'd call 'guidelines' than actual rules."
  -- Captain Barbossa, Pirates of the Caribbean, Curse of the Black Pearl

Preamble
========

This document 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.

Mentoring
=========

Why mentor?
-----------

- For most of us, we were mentored into the Project, so pay it forward
  by offering to mentor somebody else in.
- You have an irresistible urge to inflict knowledge on others.
- The usual punishment applies because you are sick and tired of committing
  somebody else's good work!

Mentor/Co-Mentor
----------------

- Reasons for a co-mentorship
  * Significant timezone differential.  Accessible, interactive mentor(s)
    available via IM is extremely helpful!
  * Potential language barrier. Yes, FreeBSD is very English oriented, as
    is most software development, however, having a mentor who can speak a
    native language can be very useful.
  * 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.
  * A rookie mentor can benefit from the experience of a senior
    committer/mentor.
  * Two heads are better than one.

- Reasons for sole mentorship
  * You do not play nicely with others :)
  * You prefer to have a one-on-one relationship
  * The reasons for co-mentorship do not apply to you

Expectations
------------

- We expect mentors to review and test-build all proposed patches, at
  least for an initial period lasting more than a week or two.

- 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.

- We expect mentors to make sure their mentees read the Porter's Handbook,
  the PR handling guide, and the Committer's Guide.  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.  Hey, there's always got to
  be at least one ...)

MENTEES
=======

Selecting a mentee
------------------

- There is no defined rule for what makes a candidate ready, it can be
  a combination of number of PRs they have spammed to gnats, the number
  ports maintained, frequency of ports updates and/or level of
  participation in a particular area of interest, e.g. Gnome, KDE, Gecko
  etc.

- A candidate should have almost no timeouts, be responsive to requests,
  and generally helpful in supporting their ports.

- There must be a history of commitment, as we all know hatching a
  committer takes time and effort.  So 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 do I get
  my @FreeBSD.org address?"

- 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.

- 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.

Duration of mentorship
----------------------

- As the trust level develops and grows, the mentee may be granted "implicit"
  commit rights.  This can include trivial changes to a Makefile, pkg-descr
  etc.  Similarly, it may include PORTVERSION updates that do not include
  plist 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.

- 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 fly solo.  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, is the number of mistakes
  they may have made, QATs received etc.  If they are still making rookie
  mistakes, they still require mentor guidance.

Mentor/Co-Mentor debate
-----------------------

- When a request gets to portmgr@, it usually reads as, "I propose 'foo' for
  a ports commit bit, I will co-mentor with 'bar'".  Proposal received, voted,
  and carried.

- The mentor is the primary point of contact or the "first among equals",
  the co-mentor is the backup.

- Some reprobate, whose name shall be withheld, made this commit
  http://lists.freebsd.org/pipermail/cvs-ports/2007-September/134614.html,
  it seems to be the first one documented in the ports tree, until somebody
  can prove otherwise.  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.

Expectations
------------

- We expect mentees to be prepared for constructive criticism from the
  community.  There's still a lot of "lore" 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.

- We warn mentees that some of the criticism they receive may be less
  "constructive" 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.

Supplementary Reading
=====================

- http://www.freebsd.org/doc/en/articles/committers-guide - The FreeBSD
  Committer's Guide

- http://www.freebsd.org/doc/en/articles/contributing-ports - Contributing
  to the FreeBSD Ports Collection

- http://www.freebsd.org/doc/en/books/porters-handbook - FreeBSD Porter's
  Handbook

Summary
=======

The thing to keep in mind is that the twin goals are to have an effective
and useful Ports Collection, with the minimum degree of interpersonal
friction, and all the while keeping in mind that this is a completely
volunteer effort, and as such is supposed to be (to some degree) fun ...

Last edited :	$Date: 2010/11/27 18:36:53 $

--
        Copyright 2010, The FreeBSD Portmgr Team.  All rights reserved.

        Redistribution, publication, translation and use, with or
        without modification, in full or in excerpt, in any form or
        format of this document are permitted.  Excerpts must be
        quoted in context and may not misconstrue the original
        meaning.

	http://people.freebsd.org/~portmgr/mentor_guidelines.txt.asc

-- 
Thomas Abthorpe		| FreeBSD Committer
tabthorpe at FreeBSD.org	| http://people.freebsd.org/~tabthorpe
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 488 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/freebsd-ports/attachments/20101130/a1ca813d/attachment.pgp