Add guidelines for ports mentoring as an article.
PR: docs/155513 (based on) Submitted by: crees Reviewed by: rene
This commit is contained in:
parent
d1dc34a663
commit
2badc4f742
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=37444
3 changed files with 253 additions and 0 deletions
|
@ -43,6 +43,7 @@ SUBDIR+= nanobsd
|
|||
SUBDIR+= new-users
|
||||
SUBDIR+= p4-primer
|
||||
SUBDIR+= pam
|
||||
SUBDIR+= port-mentor-guidelines
|
||||
SUBDIR+= portbuild
|
||||
SUBDIR+= pr-guidelines
|
||||
SUBDIR+= problem-reports
|
||||
|
|
18
en_US.ISO8859-1/articles/port-mentor-guidelines/Makefile
Normal file
18
en_US.ISO8859-1/articles/port-mentor-guidelines/Makefile
Normal file
|
@ -0,0 +1,18 @@
|
|||
#
|
||||
# $FreeBSD$
|
||||
#
|
||||
# Article: Port Mentor Guidelines
|
||||
#
|
||||
|
||||
DOC?= article
|
||||
|
||||
FORMATS?= html
|
||||
WITH_ARTICLE_TOC?= YES
|
||||
|
||||
INSTALL_COMPRESSED?= gz
|
||||
INSTALL_ONLY_COMPRESSED?=
|
||||
|
||||
SRCS= article.sgml
|
||||
|
||||
DOC_PREFIX?= ${.CURDIR}/../../..
|
||||
.include "${DOC_PREFIX}/share/mk/doc.project.mk"
|
234
en_US.ISO8859-1/articles/port-mentor-guidelines/article.sgml
Normal file
234
en_US.ISO8859-1/articles/port-mentor-guidelines/article.sgml
Normal file
|
@ -0,0 +1,234 @@
|
|||
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
|
||||
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
|
||||
%articles.ent;
|
||||
]>
|
||||
|
||||
<article>
|
||||
<articleinfo>
|
||||
<title>Port Mentor Guidelines</title>
|
||||
|
||||
<authorgroup>
|
||||
<corpauthor>The &os; Ports Management Team</corpauthor>
|
||||
</authorgroup>
|
||||
|
||||
<pubdate>$FreeBSD$</pubdate>
|
||||
|
||||
<copyright>
|
||||
<year>2011</year>
|
||||
<holder role="mailto:tabthorpe@FreeBSD.org">Thomas Abthorpe</holder>
|
||||
<holder role="mailto:crees@FreeBSD.org">Chris Rees</holder>
|
||||
</copyright>
|
||||
</articleinfo>
|
||||
|
||||
<sect1 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 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 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 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
|
||||
<ulink url="&url.books.porters-handbook;">Porter's
|
||||
Handbook</ulink>, the <ulink
|
||||
url="&url.articles.pr-guidelines">PR handling guide</ulink>, and
|
||||
the <ulink url="&url.articles.committers-guide">Committer's
|
||||
Guide</ulink>. 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.)</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 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 to
|
||||
<application>GNATS</application>, the number of ports maintained,
|
||||
frequency of ports updates and/or level of participation in a
|
||||
particular area of interest, e.g. <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 id="mentorship.duration">
|
||||
<title>Mentorship duration</title>
|
||||
|
||||
<para>As the trust level develops and grows, the mentee may be
|
||||
granted <quote>implicits</quote> commit rights. This can include
|
||||
trivial changes to a <filename>Makefile</filename>,
|
||||
<filename>pkg-descr</filename> etc. Similarly, it may include
|
||||
<makevar>PORTVERSION</makevar> updates that do not include
|
||||
<makevar>plist</makevar> 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 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
|
||||
<ulink url="http://lists.freebsd.org/pipermail/cvs-ports/2007-September/134614.html">
|
||||
first recorded co-mentor commit</ulink>. 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 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 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.</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>
|
Loading…
Reference in a new issue