830 lines
29 KiB
XML
830 lines
29 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN"
|
|
"../../../share/xml/freebsd45.dtd">
|
|
|
|
<article lang='en'>
|
|
<articleinfo>
|
|
<title>Contributing to the FreeBSD Ports Collection</title>
|
|
|
|
<abstract>
|
|
<title>Abstract</title>
|
|
|
|
<para>This article describes the ways in which an individual
|
|
can contribute to the FreeBSD Ports Collection.</para>
|
|
</abstract>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Sam</firstname>
|
|
<surname>Lawrance</surname>
|
|
</author>
|
|
<author>
|
|
<firstname>Mark</firstname>
|
|
<surname>Linimon</surname>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<legalnotice id="trademarks" role="trademarks">
|
|
&tm-attrib.freebsd;
|
|
&tm-attrib.general;
|
|
</legalnotice>
|
|
|
|
<pubdate>$FreeBSD$</pubdate>
|
|
|
|
<releaseinfo>$FreeBSD$</releaseinfo>
|
|
</articleinfo>
|
|
|
|
<indexterm><primary>contributing to ports</primary></indexterm>
|
|
|
|
<sect1>
|
|
<title>Introduction</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 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>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>
|
|
</sect1>
|
|
|
|
<sect1 id="what-contribute">
|
|
<title>What you can do to help</title>
|
|
|
|
<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 linkend="create-port"> 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>
|
|
</sect1>
|
|
|
|
<sect1 id="create-port">
|
|
<title>Creating a new port</title>
|
|
|
|
<para>There is a separate document available to help guide you
|
|
through creating (and upgrading) a port called the <ulink
|
|
url="&url.books.porters-handbook;">Porter's Handbook</ulink>.
|
|
The Porter's Handbook is the best reference to working with the
|
|
ports system. It provides details about how the ports system
|
|
operates and discusses recommended practices.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="adopt-port">
|
|
<title>Adopting an unmaintained port</title>
|
|
|
|
<sect2>
|
|
<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
|
|
<makevar>MAINTAINER</makevar> set to
|
|
<literal>ports@FreeBSD.org</literal>. A list of unmaintained
|
|
ports and their current errors and problem reports can be seen
|
|
at the <ulink
|
|
url="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">&os;
|
|
Ports Monitoring System</ulink>.</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>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<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
|
|
<ulink url="&url.books.porters-handbook;">Porter's
|
|
Handbook</ulink>. <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 <makevar>MAINTAINER</makevar>
|
|
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>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 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>
|
|
|
|
<sect2 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>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Maintainer responsibilities</title>
|
|
|
|
<sect3>
|
|
<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
|
|
<ulink url="&url.books.porters-handbook;">
|
|
Porter's Handbook</ulink>.</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 <makevar>PORTREVISION</makevar> 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 <ulink
|
|
url="&url.articles.problem-reports;">Writing FreeBSD
|
|
Problem Reports</ulink> 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 <ulink
|
|
url="&url.books.porters-handbook;/port-upgrading.html">Upgrading</ulink>
|
|
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 — 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>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<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. You should be
|
|
running <literal>7-STABLE</literal> or
|
|
<literal>8-STABLE</literal>, preferably the latter. 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>i386</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 — 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>Regularly check the automated ports building
|
|
cluster, <ulink
|
|
url="http://pointyhat.FreeBSD.org">pointyhat</ulink>,
|
|
and the <ulink url="http://www.portscout.org">distfiles
|
|
scanner</ulink> to see if any of the ports you
|
|
maintain are failing to build or fetch (see <link
|
|
linkend="resources">resources</link> for more
|
|
information about these systems). Reports of failures
|
|
may also come to you from other users or automated
|
|
systems via email.</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>pointyhat</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 <filename>INDEX</filename> file
|
|
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>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
|
|
<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
|
|
<ulink
|
|
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
|
|
GNATS Problem Report database</ulink>. 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 — 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>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Providing support</title>
|
|
|
|
<para>Part of being a maintainer is providing support —
|
|
not for the software in general — 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>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 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 <ulink
|
|
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">web
|
|
interface</ulink> 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 <ulink
|
|
url="http://portsmon.FreeBSD.org/">&os; Ports Monitoring
|
|
System</ulink>. In particular look for unmaintained ports
|
|
with build errors and ports that are marked
|
|
<makevar>BROKEN</makevar>. 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>
|
|
</sect1>
|
|
|
|
<sect1 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>
|
|
</sect1>
|
|
|
|
<sect1 id="resources">
|
|
<title>Resources for ports maintainers and contributors</title>
|
|
|
|
<para>The <ulink url="&url.books.porters-handbook;">Porter's
|
|
Handbook</ulink> is your hitchhiker's guide to the ports
|
|
system. Keep it handy!</para>
|
|
|
|
<para><ulink url="&url.articles.problem-reports;">Writing FreeBSD
|
|
Problem Reports</ulink> 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 <ulink
|
|
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
|
|
Problem Report database</ulink>.</para>
|
|
|
|
<para><ulink url="http://pointyhat.FreeBSD.org/">Pointyhat</ulink>
|
|
is the ports build cluster. You can use Pointyhat to check port
|
|
build logs across all architectures and major releases.</para>
|
|
|
|
<para>The <ulink url="http://portsmon.FreeBSD.org/">FreeBSD Ports
|
|
Monitoring System</ulink> 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 <ulink url="http://www.portscout.org">FreeBSD Ports
|
|
distfile scanner</ulink> 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
|
|
<makevar>MASTER_SITES</makevar> updated.</para>
|
|
|
|
<para>The ports <application>tinderbox</application> is the most
|
|
thorough way to test a port through the entire cycle of
|
|
installation, packaging, and deinstallation. It features a
|
|
command-line interface but also can be controlled via a web
|
|
interface. Please see
|
|
<filename>ports/ports-mgmt/tinderbox</filename>. More
|
|
documentation is located at the <ulink
|
|
url="http://tinderbox.marcuscom.com/">marcuscom tinderbox home
|
|
page</ulink>.</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 <ulink
|
|
url="&url.books.porters-handbook;">Porter's Handbook</ulink>
|
|
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 <ulink
|
|
url="http://lists.freebsd.org/mailman/listinfo">subscribe, or
|
|
read and search the list archives</ulink>. Reading the
|
|
archives of the &a.ports-bugs; and the &a.cvs-ports; may also be
|
|
of interest.</para>
|
|
</sect1>
|
|
</article>
|