contributing and contributing-ports: combine them

- combine the 'how to contribute' doc and the 'contributing to ports' doc.
- modernize the 'contributing to ports' doc
	- use &os;
	- prefer poudriere to tinderbox

Reviewed by:	crees, bapt, mat
No objections from:	bdrewery, gavin, wblock

1 files changed, 768 insertions, 13 deletions

diff --git a/en_US.ISO8859-1/articles/contributing/article.xml b/en_US.ISO8859-1/articles/contributing/article.xml
index a0fc34bb0b..b79c003fad 100644
--- a/en_US.ISO8859-1/articles/contributing/article.xml
+++ b/en_US.ISO8859-1/articles/contributing/article.xml
@@ -12,7 +12,9 @@
     </abstract>
 
     <authorgroup>
-      <author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname><contrib>Contributed by </contrib></author>
+      <author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname></author>
+      <author><personname><firstname>Sam</firstname><surname>Lawrance</surname></personname></author>
+      <author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author>
     </authorgroup>
 
     <legalnotice xml:id="trademarks" role="trademarks">
@@ -28,20 +30,22 @@
 
   <indexterm><primary>contributing</primary></indexterm>
 
-  <para>So you want to contribute to FreeBSD? That is great!  FreeBSD
+  <para>So you want to contribute to &os;? That is great!  &os;
     <emphasis>relies</emphasis> on the contributions of its user base
     to survive.  Your contributions are not only appreciated, they are
-    vital to FreeBSD's continued growth.</para>
-
-  <para>Contrary to what some people might have you believe, you do
-    not need to be a hot-shot programmer or a close personal friend of
-    the FreeBSD core team to have your contributions accepted.  A
-    large and growing number of international contributors, of greatly
-    varying ages and areas of technical expertise, develop FreeBSD.
-    There is always more work to be done than there are people
+    vital to &os;'s continued growth.</para>
+
+  <para>A large and growing number of international contributors, of
+    greatly varying ages and areas of technical expertise, develop
+    &os;.  There is always more work to be done than there are people
     available to do it, and more help is always appreciated.</para>
 
-  <para>The FreeBSD project is responsible for an entire operating
+  <para>As a volunteer, what you do is limited only by what you want
+    to do.  However, we do ask that you are aware of what other
+    members of the &os; community will expect of you.  You may want
+    to take this into account before deciding to volunteer.</para>
+
+  <para>The &os; project is responsible for an entire operating
     system environment, rather than just a kernel or a few scattered
     utilities.  As such, our <filename>TODO</filename> lists span a
     very wide range of tasks: from documentation, beta testing and
@@ -218,8 +222,53 @@
     </sect2>
 
     <sect2>
-      <title>Pick one of the items from the <quote>Ideas</quote>
-	page</title>
+      <title>Ongoing Ports Tasks</title>
+
+      <para>The Ports Collection is a perpetual work in progress.  We
+	want to provide our users with an easy to use, up to date, high
+	quality repository of third party software.  We need people to
+	donate some of their time and effort to help us achieve this
+	goal.</para>
+
+      <para>Anyone can get involved, and there are lots of different
+	ways to do so.  Contributing to ports is an excellent way to
+	help <quote>give&nbsp;back</quote> something to the project.
+	Whether you are looking for an ongoing role, or a fun challenge
+	for a rainy day, we would love to have your help!</para>
+
+      <para>There are a number of easy ways you can contribute to
+	keeping the ports tree up to date and in good working
+	order:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Find some cool or useful software and
+	    <link xlink:href="&url.books.porters-handbook;">create a port</link>
+	    for it.</para>
+	</listitem>
+
+	<listitem>
+	  <para>There are a large number of ports that have no
+	    maintainer.  Become a maintainer and
+	    <link linkend="adopt-port">adopt a port</link>.</para>
+	</listitem>
+
+	<listitem>
+	  <para>If you have created or adopted a port, be
+	    aware of <link linkend="maintain-port">what you need to do
+	      as a maintainer</link>.</para>
+	</listitem>
+
+	<listitem>
+	  <para>When you are looking for a quick challenge you
+	    could <link linkend="fix-broken">fix a bug or a broken
+	      port</link>.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Pick one of the items from the Ideas page</title>
 
       <para>The <link xlink:href="http://wiki.freebsd.org/IdeasPage">&os;
 	  list of projects and ideas for volunteers</link> is also
@@ -441,5 +490,711 @@
     </sect2>
   </sect1>
 
+  <sect1 xml:id="ports-contributing">
+    <title>Contributing to ports</title>
+
+    <sect2 xml:id="adopt-port">
+      <title>Adopting an unmaintained port</title>
+
+      <sect3>
+	<title>Choosing an unmaintained port</title>
+
+	<para>Taking over maintainership of ports that are
+	  unmaintained is a great way to get involved.  Unmaintained
+	  ports are only updated and fixed when somebody volunteers to
+	  work on them.  There are a large number of unmaintained
+	  ports.  It is a good idea to start with adopting a port that
+	  you use regularly.</para>
+
+	<para>Unmaintained ports have their
+	  <varname>MAINTAINER</varname> set to
+	  <literal>ports@FreeBSD.org</literal>.  A list of unmaintained
+	  ports and their current errors and problem reports can be seen
+	  at the <link xlink:href="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">&os;
+	    Ports Monitoring System</link>.</para>
+
+	<para>Some ports affect a large number of others due to
+	  dependencies and slave port relationships.  Generally, we
+	  want people to have some experience before they maintain such
+	  ports.</para>
+
+	<para>You can find out whether or not a port has dependencies
+	  or slave ports by looking at a master index of ports called
+	  <filename>INDEX</filename>.  (The name of the file varies
+	  by release of &os;; for instance,
+	  <filename>INDEX-8</filename>.) Some ports have conditional
+	  dependencies that are not included in a default
+	  <filename>INDEX</filename> build.  We expect you to be able to
+	  recognize such ports by looking through other ports'
+	  <filename>Makefile</filename>s.</para>
+      </sect3>
+
+      <sect3>
+	<title>How to adopt the port</title>
+
+	<para>First make sure you understand your
+	  <link linkend="maintain-port">responsibilities as a
+	    maintainer</link>.  Also read the
+	  <link xlink:href="&url.books.porters-handbook;">Porter's
+	    Handbook</link>.  <emphasis>Please do not commit yourself
+	    to more than you feel you can comfortably
+	    handle.</emphasis></para>
+
+	<para>You may request maintainership of any unmaintained port
+	  as soon as you wish.  Simply set <varname>MAINTAINER</varname>
+	  to your own email address and send a PR (Problem Report) with
+	  the change.  If the port has build errors or needs updating,
+	  you may wish to include any other changes in the same PR.
+	  This will help because many committers are less willing to
+	  assign maintainership to someone who does not have a known
+	  track record with &os;.  Submitting PRs that fix build errors
+	  or update ports are the best ways to establish one.</para>
+
+	<para>File your PR with category <literal>ports</literal> and
+	  class <literal>change-request</literal>.  A committer will
+	  examine your PR, commit the changes, and finally close the
+	  PR.  Sometimes this process can take a little while
+	  (committers are volunteers, too :).</para>
+      </sect3>
+    </sect2>
+
+    <sect2 xml:id="maintain-port">
+      <title>The challenge for port maintainers</title>
+
+      <para>This section will give you an idea of why ports need to be
+	maintained and outline the responsibilities of a port
+	maintainer.</para>
+
+      <sect3 xml:id="why-maintenance">
+	<title>Why ports require maintenance</title>
+
+	<para>Creating a port is a once-off task.  Ensuring that a
+	  port is up to date and continues to build and run requires
+	  an ongoing maintenance effort.  Maintainers are the people
+	  who dedicate some of their time to meeting these goals.</para>
+
+	<para>The foremost reason ports need maintenance is to bring
+	  the latest and greatest in third party software to the &os;
+	  community.  An additional challenge is to keep individual
+	  ports working within the Ports Collection framework as it
+	  evolves.</para>
+
+	<para>As a maintainer, you will need to manage the following
+	  challenges:</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <formalpara>
+	      <title>New software versions and updates.</title>
+
+	      <para>New versions and updates of existing ported
+		software become available all the time, and these need
+		to be incorporated into the Ports Collection in order
+		to provide up-to-date software.</para>
+	    </formalpara>
+	  </listitem>
+
+	  <listitem>
+	    <formalpara>
+	      <title>Changes to dependencies.</title>
+
+	      <para>If significant changes are made to the dependencies
+		of your port, it may need to be updated so that it will
+		continue to work correctly.</para>
+	    </formalpara>
+	  </listitem>
+
+	  <listitem>
+	    <formalpara>
+	      <title>Changes affecting dependent ports.</title>
+
+	      <para>If other ports depend on a port that you maintain,
+		changes to your port may require coordination with
+		other maintainers.</para>
+	    </formalpara>
+	  </listitem>
+
+	  <listitem>
+	    <formalpara>
+	      <title>Interaction with other users, maintainers and
+		developers.</title>
+
+	      <para>Part of being a maintainer is taking on a support
+		role.  You are not expected to provide general support
+		(but we welcome it if you choose to do so).  What you
+		should provide is a point of coordination for
+		&os;-specific issues regarding your ports.</para>
+	    </formalpara>
+	  </listitem>
+
+	  <listitem>
+	    <formalpara>
+	      <title>Bug hunting.</title>
+
+	      <para>A port may be affected by bugs which are specific
+		to &os;.  You will need to investigate, find, and fix
+		these bugs when they are reported.  Thoroughly testing
+		a port to identify problems before they make their way
+		into the Ports Collection is even better.</para>
+	    </formalpara>
+	  </listitem>
+
+	  <listitem>
+	    <formalpara>
+	      <title>Changes to ports infrastructure and policy.</title>
+
+	      <para>Occasionally the systems that are used to build
+		ports and packages are updated or a new recommendation
+		affecting the infrastructure is made.  You should be
+		aware of these changes in case your ports are affected
+		and require updating.</para>
+	    </formalpara>
+	  </listitem>
+
+	  <listitem>
+	    <formalpara>
+	      <title>Changes to the base system.</title>
+
+	      <para>&os; is under constant development.  Changes to
+		software, libraries, the kernel or even policy changes
+		can cause flow-on change requirements to ports.</para>
+	    </formalpara>
+	  </listitem>
+	</itemizedlist>
+      </sect3>
+
+      <sect3>
+	<title>Maintainer responsibilities</title>
+
+	<sect4>
+	  <title>Keep your ports up to date</title>
+
+	  <para>This section outlines the process to follow to keep your
+	    ports up to date.</para>
+
+	  <para>This is an overview.  More information about upgrading a
+	    port is available in the
+	    <link xlink:href="&url.books.porters-handbook;">
+	      Porter's Handbook</link>.</para>
+
+	  <procedure>
+	    <step>
+	      <title>Watch for updates</title>
+
+	      <para>Monitor the upstream vendor for new versions,
+		updates and security fixes for the software.
+		Announcement mailing lists or news web pages are useful
+		for doing this.  Sometimes users will contact you and
+		ask when your port will be updated.  If you are busy
+		with other things or for any reason just cannot update
+		it at the moment, ask if they will help you by
+		submitting an update.</para>
+
+	      <para>You may also receive automated email from the
+		<literal>&os; Ports Version Check</literal> informing
+		you that a newer version of your port's distfile is
+		available.  More information about that system
+		(including how to stop future emails) will be provided
+		in the message.</para>
+	    </step>
+
+	    <step>
+	      <title>Incorporate changes</title>
+
+	      <para>When they become available, incorporate the changes
+		into the port.  You need to be able to generate a patch
+		between the original port and your updated port.</para>
+	    </step>
+
+	    <step>
+	      <title>Review and test</title>
+
+	      <para>Thoroughly review and test your changes:</para>
+
+	      <itemizedlist>
+		<listitem>
+		  <para>Build, install and test your port on as many
+		    platforms and architectures as you can.  It is
+		    common for a port to work on one branch or platform
+		    and fail on another.</para>
+		</listitem>
+
+		<listitem>
+		  <para>Make sure your port's dependencies are complete.
+		    The recommended way of doing this is by installing
+		    your own ports <application>tinderbox</application>.
+		    See <link linkend="resources">resources</link>
+		    for more information.</para>
+		</listitem>
+
+		<listitem>
+		  <para>Check that the packing list is up to date.  This
+		    involves adding in any new files and directories and
+		    removing unused entries.</para>
+		</listitem>
+
+		<listitem>
+		  <para>Verify your port using &man.portlint.1; as a
+		    guide.  See <link linkend="resources">resources</link> for important
+		    information about using
+		    <application>portlint</application>.</para>
+		</listitem>
+
+		<listitem>
+		  <para>Consider whether changes to your port might
+		    cause any other ports to break.  If this is the
+		    case, coordinate the changes with the maintainers of
+		    those ports.  This is especially important if your
+		    update changes the shared library version; in this
+		    case, at the very least, the dependent ports will
+		    need to get a <varname>PORTREVISION</varname> bump
+		    so that they will automatically be upgraded by
+		    automated tools such as
+		    <application>portmaster</application> or
+		    &man.portupgrade.1;.</para>
+		</listitem>
+	      </itemizedlist>
+	    </step>
+
+	    <step>
+	      <title>Submit changes</title>
+
+	      <para>Send your update by submitting a PR with an
+		explanation of the changes and a patch containing the
+		differences between the original port and the updated
+		one.  Please refer to <link xlink:href="&url.articles.problem-reports;">Writing FreeBSD
+		  Problem Reports</link> for information on how to
+		write a really good PR.</para>
+
+	      <note>
+		<para>Please do not submit a &man.shar.1; archive of the
+		  entire port; instead, use &man.diff.1;
+		  <literal>-ruN</literal>.  In this way, committers can
+		  much more easily see exactly what changes are being
+		  made.  The Porter's Handbook section on <link xlink:href="&url.books.porters-handbook;/port-upgrading.html">Upgrading</link>
+		  has more information.</para>
+	      </note>
+	    </step>
+
+	    <step>
+	      <title>Wait</title>
+
+	      <para>At some stage a committer will deal with your PR.
+		It may take minutes, or it may take weeks &mdash; so
+		please be patient.</para>
+	    </step>
+
+	    <step>
+	      <title>Give feedback</title>
+
+	      <para>If a committer finds a problem with your changes,
+		they will most likely refer it back to you.  A prompt
+		response will help get your PR committed faster, and
+		is better for maintaining a thread of conversation
+		when trying to resolve any problems.</para>
+	    </step>
+
+	    <step>
+	      <title>And Finally</title>
+
+	      <para>Your changes will be committed and your port will
+		have been updated.  The PR will then be closed by the
+		committer.  That's it!</para>
+	    </step>
+	  </procedure>
+	</sect4>
+
+	<sect4>
+	  <title>Ensure your ports continue to build correctly</title>
+
+	  <para>This section is about discovering and fixing problems
+	    that stop your ports from building correctly.</para>
+
+	  <para>&os; only guarantees that the Ports Collection works on
+	    the <literal>-STABLE</literal> branches.
+	    In
+	    theory, you should be able to get by with running the latest
+	    release of each stable branch (since the ABIs are not
+	    supposed to change) but if you can run the branch, that is
+	    even better.</para>
+
+	  <para>Since the majority of &os; installations run on
+	    PC-compatible machines (what is termed the
+	    <literal>i386</literal> architecture), we expect you to keep
+	    the port working on that architecture.  We prefer that ports
+	    also work on the <literal>amd64</literal> architecture
+	    running native.  It is completely fair to ask for help if
+	    you do not have one of these machines.</para>
+
+	  <note>
+	    <para>The usual failure modes for
+	      non-<literal>x86</literal> machines are that the original
+	      programmers assumed that, for instance, pointers are
+	      <literal>int</literal>s, or that a relatively lax older
+	      <application>gcc</application> compiler was being used.
+	      More and more, application authors are reworking their
+	      code to remove these assumptions &mdash; but if the author
+	      is not actively maintaining their code, you may need to do
+	      this yourself.</para>
+	  </note>
+
+	  <para>These are the tasks you need to perform to ensure your
+	    port is able to be built:</para>
+
+	  <procedure>
+	    <step>
+	      <title>Watch for build failures</title>
+
+	      <para>Check your mail for mail from
+		<literal>pkg-fallout@FreeBSD.org</literal> 
+		and the <link xlink:href="http://portscout.FreeBSD.org">distfiles scanner</link>
+		to see if any of the port which are failing to build
+		are out of date.</para>
+	    </step>
+
+	    <step>
+	      <title>Collect information</title>
+
+	      <para>Once you are aware of a problem, collect information
+		to help you fix it.  Build errors reported by
+		<literal>pkg-fallout</literal> are accompanied by logs
+		which will show you where the build failed.  If the
+		failure was reported to you by a user, ask them to send
+		you information which may help in diagnosing the
+		problem, such as:</para>
+
+	      <itemizedlist>
+		<listitem>
+		  <para>Build logs</para>
+		</listitem>
+
+		<listitem>
+		  <para>The commands and options used to build the
+		    port (including options set in
+		    <filename>/etc/make.conf</filename>)</para>
+		</listitem>
+
+		<listitem>
+		  <para>A list of packages installed on their system
+		    as shown by &man.pkg.info.1;</para>
+		</listitem>
+
+		<listitem>
+		  <para>The version of &os; they are running as
+		    shown by &man.uname.1;<command> -a</command></para>
+		</listitem>
+
+		<listitem>
+		  <para>When their ports collection was last
+		    updated</para>
+		</listitem>
+
+		<listitem>
+		  <para>When their ports tree amd
+		  <filename>INDEX</filename> was last updated</para>
+		</listitem>
+	      </itemizedlist>
+	    </step>
+
+	    <step>
+	      <title>Investigate and find a solution</title>
+
+	      <para>Unfortunately there is no straightforward process to
+		follow to do this.  Remember, though: if you are stuck,
+		ask for help!  The &a.ports; is a good place to start,
+		and the upstream developers are often very
+		helpful.</para>
+	    </step>
+
+	    <step>
+	      <title>Submit changes</title>
+
+	      <para>Just as with updating a port, you should now
+		incorporate changes, review and test, submit your
+		changes in a PR, and provide feedback if
+		required.</para>
+	    </step>
+
+	    <step>
+	      <title>Send patches to upstream authors</title>
+
+	      <para>In some cases, you will have to make patches to the
+		port to make it run on FreeBSD.  Some (but not all)
+		upstream authors will accept such patches back into
+		their code for the next release.  If so, this may even
+		help their users on other BSD-based systems as well and
+		perhaps save duplicated effort.  Please consider sending
+		any applicable patches to the authors as a
+		courtesy.</para>
+	    </step>
+	  </procedure>
+	</sect4>
+
+	<sect4>
+
+	  <title>Investigate bug reports and PRs related to your
+	    port</title>
+
+	  <para>This section is about discovering and fixing
+	    bugs.</para>
+
+	  <para>&os;-specific bugs are generally caused by assumptions
+	    about the build and runtime environments that do not apply
+	    to &os;.  You are less likely to encounter a problem of this
+	    type, but it can be more subtle and difficult to
+	    diagnose.</para>
+
+	  <para>These are the tasks you need to perform to ensure your
+	    port continues to work as intended:</para>
+
+	  <procedure>
+	    <step>
+	      <title>Respond to bug reports</title>
+
+	      <para>Bugs may be reported to you through email via the
+		<link xlink:href="https://bugs.FreeBSD.org/search/">
+		Problem Report database</link>.  Bugs may also be
+		reported directly to you by users.</para>
+
+	      <para>You should respond to PRs and other reports within
+		14 days, but please try not to take that long.  Try to
+		respond as soon as possible, even if it is just to say
+		you need some more time before you can work on the
+		PR.</para>
+
+	      <para>If you have not responded after 14 days, any
+		committer may commit from a PR that you have not
+		responded to via a
+		<literal>maintainer-timeout</literal>.</para>
+	    </step>
+
+	    <step>
+	      <title>Collect information</title>
+
+	      <para>If the person reporting the bug has not also
+		provided a fix, you need to collect the information that
+		will allow you to generate one.</para>
+
+	      <para>If the bug is reproducible, you can collect most of
+		the required information yourself.  If not, ask the
+		person who reported the bug to collect the information
+		for you, such as:</para>
+
+	      <itemizedlist>
+		<listitem>
+		  <para>A detailed description of their actions,
+		    expected program behavior and actual behavior</para>
+		</listitem>
+
+		<listitem>
+		  <para>Copies of input data used to trigger the
+		    bug</para>
+		</listitem>
+
+		<listitem>
+		  <para>Information about their build and execution
+		    environment &mdash; for example, a list of installed
+		    packages and the output of &man.env.1;</para>
+		</listitem>
+
+		<listitem>
+		  <para>Core dumps</para>
+		</listitem>
+
+		<listitem>
+		  <para>Stack traces</para>
+		</listitem>
+	      </itemizedlist>
+	    </step>
+
+	    <step>
+	      <title>Eliminate incorrect reports</title>
+
+	      <para>Some bug reports may be incorrect.  For example,
+		the user may have simply misused the program; or their
+		installed packages may be out of date and require
+		updating.  Sometimes a reported bug is not specific to
+		&os;.  In this case report the bug to the upstream
+		developers.  If the bug is within your capabilities to
+		fix, you can also patch the port so that the fix is
+		applied before the next upstream release.</para>
+	    </step>
+
+	    <step>
+	      <title>Find a solution</title>
+
+	      <para>As with build errors, you will need to sort out a
+		fix to the problem.  Again, remember to ask if you are
+		stuck!</para>
+	    </step>
+
+	    <step>
+	      <title>Submit or approve changes</title>
+
+	      <para>Just as with updating a port, you should now
+		incorporate changes, review and test, and submit your
+		changes in a PR (or send a follow-up if a PR already
+		exists for the problem).  If another user has submitted
+		changes in the PR, you can also send a follow-up saying
+		whether or not you approve the changes.</para>
+	    </step>
+	  </procedure>
+	</sect4>
+
+	<sect4>
+	  <title>Providing support</title>
+
+	  <para>Part of being a maintainer is providing support &mdash;
+	    not for the software in general &mdash; but for the port and
+	    any &os;-specific quirks and problems.  Users may contact
+	    you with questions, suggestions, problems and patches.  Most
+	    of the time their correspondence will be specific to
+	    &os;.</para>
+
+	  <para>Occasionally you may have to invoke your skills in
+	    diplomacy, and kindly point users seeking general support to
+	    the appropriate resources.  Less frequently you will
+	    encounter a person asking why the <literal>RPM</literal>s
+	    are not up to date or how can they get the software to run
+	    under Foo Linux.  Take the opportunity to tell them that
+	    your port is up to date (if it is, of course!), and suggest
+	    that they try &os;.</para>
+
+	  <para>Sometimes users and developers will decide that you are
+	    a busy person whose time is valuable and do some of the work
+	    for you.  For example, they might:</para>
+
+	  <itemizedlist>
+	    <listitem>
+	      <para>submit a PR or send you patches to update your
+		port,</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>investigate and perhaps provide a fix to a PR,
+		or</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>otherwise submit changes to your port.</para>
+	    </listitem>
+	  </itemizedlist>
+
+	  <para>In these cases your main obligation is to respond in a
+	    timely manner.  Again, the timeout for non-responsive
+	    maintainers is 14 days.  After this period changes may be
+	    committed unapproved.  They have taken the trouble to do
+	    this for you; so please try to at least respond promptly.
+	    Then review, approve, modify or discuss their changes with
+	    them as soon as possible.</para>
+
+	  <para>If you can make them feel that their contribution is
+	    appreciated (and it should be) you will have a better chance
+	    persuading them to do more things for you in the future
+	    <!-- smiley -->:-).</para>
+	</sect4>
+      </sect3>
+    </sect2>
+
+    <sect2 xml:id="fix-broken">
+      <title>Finding and fixing a broken port</title>
+
+      <para>There are two really good places to find a port that needs
+	some attention.</para>
+
+      <para>You can use the <link xlink:href="http://bugs.freebsd.org/search">web
+	  interface</link> to the Problem Report database to search
+	through and view unresolved PRs.  The majority of ports PRs are
+	updates, but with a little searching and skimming over synopses
+	you should be able to find something interesting to work on (the
+	<literal>sw-bug</literal> class is a good place to
+	start).</para>
+
+      <para>The other place is the <link xlink:href="http://portsmon.FreeBSD.org/">&os; Ports Monitoring
+	  System</link>.  In particular look for unmaintained ports
+	with build errors and ports that are marked
+	<varname>BROKEN</varname>.  It is OK to send changes for a
+	maintained port as well, but remember to ask the maintainer in
+	case they are already working on the problem.</para>
+
+      <para>Once you have found a bug or problem, collect information,
+	investigate and fix!  If there is an existing PR, follow up to
+	that.  Otherwise create a new PR.  Your changes will be reviewed
+	and, if everything checks out, committed.</para>
+    </sect2>
+
+    <sect2 xml:id="mortal-coil">
+      <title>When to call it quits</title>
+
+      <para>As your interests and commitments change, you may find that
+	you no longer have time to continue some (or all) of your ports
+	contributions.  That is fine!  Please let us know if you are no
+	longer using a port or have otherwise lost time or interest in
+	being a maintainer.  In this way we can go ahead and allow other
+	people to try to work on existing problems with the port without
+	waiting for your response.  Remember, &os; is a volunteer
+	project, so if maintaining a port is no fun anymore, it is
+	probably time to let someone else do it!</para>
+
+      <para>In any case, the Ports Management Team
+	(<literal>portmgr</literal>) reserves the right to reset your
+	maintainership if you have not actively maintained your port in
+	some time.  (Currently, this is set to 3 months.)  By this, we
+	mean that there are unresolved problems or pending updates that
+	have not been worked on during that time.</para>
+    </sect2>
+
+    <sect2 xml:id="resources">
+      <title>Resources for ports maintainers and contributors</title>
+
+      <para>The <link xlink:href="&url.books.porters-handbook;">Porter's
+	  Handbook</link> is your hitchhiker's guide to the ports
+	system.  Keep it handy!</para>
+
+      <para><link xlink:href="&url.articles.problem-reports;">Writing FreeBSD
+	  Problem Reports</link> describes how to best formulate and
+	submit a PR.  In 2005 more than eleven thousand ports PRs were
+	submitted!  Following this article will greatly assist us in
+	reducing the time needed to handle your PRs.</para>
+
+      <para>The <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
+	  Problem Report database</link>.</para>
+
+      <para>The <link xlink:href="http://portsmon.FreeBSD.org/">FreeBSD Ports
+	  Monitoring System</link> can show you cross-referenced
+	information about ports such as build errors and problem
+	reports.  If you are a maintainer you can use it to check on the
+	build status of your ports.  As a contributor you can use it to
+	find broken and unmaintained ports that need to be fixed.</para>
+
+      <para>The <link xlink:href="http://portscout.FreeBSD.org">FreeBSD Ports
+	  distfile scanner</link> can show you ports for which the
+	distfiles are not fetchable.  You can check on your own ports or
+	use it to find ports that need their
+	<varname>MASTER_SITES</varname> updated.</para>
+
+      <para><package>ports-mgmt/poudriere</package> is the most
+	thorough way to test a port through the entire cycle of
+	installation, packaging, and deinstallation.
+	documentation is located at the
+	<link xlink:href="https://fossil.etoilebsd.net/poudriere/">poudriere home page</link></para>
+
+      <para>&man.portlint.1; is an application which can be used to
+	verify that your port conforms to many important stylistic and
+	functional guidelines.  <application>portlint</application> is a
+	simple heuristic application, so you should use it
+	<emphasis>only as a guide</emphasis>.  If
+	<application>portlint</application> suggests changes which seem
+	unreasonable, consult the <link xlink:href="&url.books.porters-handbook;">Porter's Handbook</link>
+	or ask for advice.</para>
+
+      <para>The &a.ports; is for general ports-related discussion.  It
+	is a good place to ask for help.  You can <link xlink:href="http://lists.freebsd.org/mailman/listinfo">subscribe, or
+	  read and search the list archives</link>.  Reading the
+	archives of the &a.ports-bugs; and the &a.cvs-ports; may also be
+	of interest.</para>
+    </sect2>
+  </sect1>
+
   <index/>
 </article>