Things all ports mentors and potential mentees should know
tabthorpe at FreeBSD.org
Tue Nov 30 15:08:40 UTC 2010
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,
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
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.
- 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!
- 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
* 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
- 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 ...)
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
- 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.
- 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,
- 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
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.
- 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
- 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.
- http://www.freebsd.org/doc/en/articles/committers-guide - The FreeBSD
- 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
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
Thomas Abthorpe | FreeBSD Committer
tabthorpe at FreeBSD.org | http://people.freebsd.org/~tabthorpe
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 488 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/freebsd-ports/attachments/20101130/a1ca813d/attachment.pgp
More information about the freebsd-ports