Date: Tue, 30 Nov 2010 10:08:39 -0500 From: Thomas Abthorpe <tabthorpe@FreeBSD.org> To: ports@FreeBSD.org Subject: Things all ports mentors and potential mentees should know Message-ID: <20101130150839.GH52404@hub.freebsd.org>
next in thread | raw e-mail | index | archive | help
--D6IIOQQv2Iwyp54J
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
"The code is more what you'd call 'guidelines' than actual rules."
-- Captain Barbossa, Pirates of the Caribbean, Curse of the Black Pearl
Preamble
=3D=3D=3D=3D=3D=3D=3D=3D
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
=3D=3D=3D=3D=3D=3D=3D=3D=3D
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
=3D=3D=3D=3D=3D=3D=3D
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 "implici=
t"
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, vot=
ed,
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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
- 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
=3D=3D=3D=3D=3D=3D=3D
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
--=20
Thomas Abthorpe | FreeBSD Committer
tabthorpe@FreeBSD.org | http://people.freebsd.org/~tabthorpe
--D6IIOQQv2Iwyp54J
Content-Type: application/pgp-signature
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (FreeBSD)
iQEcBAEBAgAGBQJM9RN2AAoJENk3EJekc8mQW6IH/jvzceHyl3PD6XctR+Vny5bC
T0EcnT8r6AFNTPzfnVBD95NPGhw4/RDQ6Q7go1VF/te1EYTf5bMxCbwAZuzPaa/L
9zfMm8ynKLrEAsVJ5GzC9HeTvQdklzQ9Jj9JzQsVsccsJjZaVvuFrgn8KU/fwNjN
nAGKQd05GIdUh7eQL4X3Db0qc7EtSZNeqDuGVhQpSJl4QEeBmnOUZLMbvCj9a3OR
Nh9d5Fd7JWzdi/2xqqLXXYCFW3XjZ/eHPeEwi9kx3+DKaVe9zR7Nf2rSVqmtktSm
jIxG+/cyTbeq7Qkj82fzJwlZwO0RjGvR/PsKKrEJtoJpwoq/Dn93UIOh7sM2akg=
=qImZ
-----END PGP SIGNATURE-----
--D6IIOQQv2Iwyp54J--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20101130150839.GH52404>