From owner-freebsd-doc@FreeBSD.ORG Sun Mar 13 09:10:08 2011 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id A6CA41065672 for ; Sun, 13 Mar 2011 09:10:08 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 593558FC0C for ; Sun, 13 Mar 2011 09:10:08 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.4/8.14.4) with ESMTP id p2D9A8d7091735 for ; Sun, 13 Mar 2011 09:10:08 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.4/8.14.4/Submit) id p2D9A8eP091734; Sun, 13 Mar 2011 09:10:08 GMT (envelope-from gnats) Resent-Date: Sun, 13 Mar 2011 09:10:08 GMT Resent-Message-Id: <201103130910.p2D9A8eP091734@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Chris Rees Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 45A781065673 for ; 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 ; 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 ; 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 To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Cc: Subject: docs/155513: New chapter for Committer's Guide: Mentor Guidelines from portmgr X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Chris Rees List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 13 Mar 2011 09:10:08 -0000 >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@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 @@ + + Guideline for Mentor/Mentee relationships + + 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. + + + Why mentor? + + + + For most of us, we were mentored into the + Project, so return the favor 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, &os; 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.) + + + + 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 + submitted to GNATS, the number + of ports maintained, frequency of ports updates and/or level of + participation in a particular area of interest, e.g. + GNOME, KDE, + Gecko or others. + + 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 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. + + 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. + + + + Mentorship duration + + As the trust level develops and grows, the mentee may be granted + implicits 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 are 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 the + + first recorded co-mentor commit. + 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. + + + + Preferred License for New Files --- mentor_mentee_guidelines.diff ends here --- >Release-Note: >Audit-Trail: >Unformatted: