os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add a new article about how to contribute to the FreeBSD Ports Collection,

Browse source 
oriented to both current and potential maintainers.
This commit is contained in:
Mark Linimon 2005-10-17 05:52:59 +00:00
parent b325073e13
commit 1b9d53fd67
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=26046
2 changed files with 821 additions and 0 deletions
en_US.ISO8859-1/articles/contributing-ports
Makefilearticle.sgml

19
en_US.ISO8859-1/articles/contributing-ports/Makefile Normal file
View file

@ -0,0 +1,19 @@
#
# $FreeBSD$
#
# Article: Contributing to the FreeBSD Ports Collection
DOC?= article
FORMATS?= html
WITH_ARTICLE_TOC?= YES
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.sgml
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

802
en_US.ISO8859-1/articles/contributing-ports/article.sgml Normal file
View file

@ -0,0 +1,802 @@
<!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;
<!ENTITY % not.published "IGNORE">
]>
<article>
<articleinfo>
<title>Contributing to the FreeBSD Ports Collection</title>
<pubdate>$FreeBSD$</pubdate>
<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>
</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 "give&nbsp;back" 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-6</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>.
<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.
If you have the resources, a good way of doing this
is building and testing the port
&man.chroot.8;'ed inside a newly
installed world.</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>
<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 &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>
</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>5-STABLE</literal> or
<literal>6-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. However, as more and more people start using
the <literal>amd64</literal> architecture running native, it is
going to be more and more important to make sure that ports run
there as well. 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 the
relatively lax <application>gcc</application>&nbsp;2.95 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>Regularly check the automated ports building cluster,
<ulink url="http://pointyhat.FreeBSD.org">pointyhat</ulink>,
and the
<ulink url="http://people.FreeBSD.org/~fenner/portsurvey/">distfiles survey</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>
</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 &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. 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 2004 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>Bill Fenner's
<ulink url="http://people.FreeBSD.org/~fenner/portsurvey/">distfile survey</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>&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 Porter's Handbook 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>
<!--
Local Variables:
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
End:
-->