2094ad2036
PR: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=203808 Submitted by: Hoyoung Kim <trig4800@gmail.com>
1200 lines
44 KiB
XML
1200 lines
44 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
|
|
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
|
|
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
|
|
<info><title>Contributing to FreeBSD</title>
|
|
|
|
|
|
<abstract>
|
|
<para>This article describes the different ways in which an
|
|
individual or organization may contribute to the FreeBSD
|
|
Project.</para>
|
|
</abstract>
|
|
|
|
<authorgroup>
|
|
<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">
|
|
&tm-attrib.freebsd;
|
|
&tm-attrib.ieee;
|
|
&tm-attrib.general;
|
|
</legalnotice>
|
|
|
|
<pubdate>$FreeBSD$</pubdate>
|
|
|
|
<releaseinfo>$FreeBSD$</releaseinfo>
|
|
</info>
|
|
|
|
<indexterm><primary>contributing</primary></indexterm>
|
|
|
|
<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 &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>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
|
|
presentation, to the system installer and highly specialized types
|
|
of kernel development. People of any skill level, in almost any
|
|
area, can almost certainly help the project.</para>
|
|
|
|
<para>Commercial entities engaged in FreeBSD-related enterprises are
|
|
also encouraged to contact us. Do you need a special extension to
|
|
make your product work? You will find us receptive to your
|
|
requests, given that they are not too outlandish. Are you working
|
|
on a value-added product? Please let us know! We may be able to
|
|
work cooperatively on some aspect of it. The free software world
|
|
is challenging many existing assumptions about how software is
|
|
developed, sold, and maintained, and we urge you to at least give
|
|
it a second look.</para>
|
|
|
|
<sect1 xml:id="contrib-what">
|
|
<title>What Is Needed</title>
|
|
|
|
<para>The following list of tasks and sub-projects represents
|
|
something of an amalgam of various <filename>TODO</filename>
|
|
lists and user requests.</para>
|
|
|
|
<sect2 xml:id="non-programmer-tasks">
|
|
<title>Ongoing Non-Programmer Tasks</title>
|
|
|
|
<para>Many people who are involved in FreeBSD are not
|
|
programmers. The Project includes documentation writers, Web
|
|
designers, and support people. All that these people need to
|
|
contribute is an investment of time and a willingness to
|
|
learn.</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Read through the FAQ and Handbook periodically. If
|
|
anything is badly explained, out of date or even just
|
|
completely wrong, let us know. Even better, send us a fix
|
|
(Docbook is not difficult to learn, but there is no
|
|
objection to ASCII submissions).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Help translate FreeBSD documentation into your native
|
|
language. If documentation already exists for your
|
|
language, you can help translate additional documents or
|
|
verify that the translations are up-to-date. First take a
|
|
look at the <link xlink:href="&url.books.fdp-primer;/translations.html">Translations
|
|
FAQ</link> in the FreeBSD Documentation Project Primer.
|
|
You are not committing yourself to translating every
|
|
single FreeBSD document by doing this — as a
|
|
volunteer, you can do as much or as little translation as
|
|
you desire. Once someone begins translating, others
|
|
almost always join the effort. If you only have the time
|
|
or energy to translate one part of the documentation,
|
|
please translate the installation instructions.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Read the &a.questions; occasionally (or
|
|
even regularly). It can be very satisfying to share your
|
|
expertise and help people solve their problems; sometimes
|
|
you may even learn something new yourself! These forums
|
|
can also be a source of ideas for things to work
|
|
on.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="ongoing-programmer-tasks">
|
|
<title>Ongoing Programmer Tasks</title>
|
|
|
|
<para>Most of the tasks listed here require either a
|
|
considerable investment of time, or an in-depth knowledge of
|
|
the FreeBSD kernel, or both. However, there are also many
|
|
useful tasks which are suitable for
|
|
<quote>weekend hackers</quote>.</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>If you run FreeBSD-CURRENT and have a good Internet
|
|
connection, there is a machine
|
|
<systemitem class="fqdomainname">current.FreeBSD.org</systemitem> which
|
|
builds a full release once a day—every now and
|
|
again, try to install the latest release from it and
|
|
report any failures in the process.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Read the &a.bugs;. There might be a problem you can
|
|
comment constructively on or with patches you can test.
|
|
Or you could even try to fix one of the problems
|
|
yourself.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you know of any bug fixes which have been
|
|
successfully applied to -CURRENT but have not been merged
|
|
into -STABLE after a decent interval (normally a couple of
|
|
weeks), send the committer a polite reminder.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Move contributed software to
|
|
<filename>src/contrib</filename> in the
|
|
source tree.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Make sure code in
|
|
<filename>src/contrib</filename> is up
|
|
to date.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Build the source tree (or just part of it) with extra
|
|
warnings enabled and clean up the warnings.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Fix warnings for ports which do deprecated things like
|
|
using <function>gets()</function> or including
|
|
<filename>malloc.h</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you have contributed any ports and you had to make
|
|
&os;-specific changes, send your patches back to the
|
|
original authors (this will make your life easier when
|
|
they bring out the next version).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Get copies of formal standards like &posix;.
|
|
Compare FreeBSD's behavior to that required by
|
|
the standard. If the behavior differs, particularly in
|
|
subtle or obscure corners of the specification, send in a
|
|
PR about it. If you are able, figure out how to fix it
|
|
and include a patch in the PR. If you think the standard
|
|
is wrong, ask the standards body to consider the
|
|
question.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Suggest further tasks for this list!</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Work through the PR Database</title>
|
|
|
|
<indexterm>
|
|
<primary>problem reports database</primary>
|
|
</indexterm>
|
|
|
|
<para>The <link xlink:href="https://bugs.FreeBSD.org/search/">FreeBSD
|
|
PR list</link> shows all the current active problem reports
|
|
and requests for enhancement that have been submitted by
|
|
FreeBSD users. The PR database includes both programmer and
|
|
non-programmer tasks. Look through the open PRs, and see if
|
|
anything there takes your interest. Some of these might be
|
|
very simple tasks that just need an extra pair of eyes to look
|
|
over them and confirm that the fix in the PR is a good one.
|
|
Others might be much more complex, or might not even have a
|
|
fix included at all.</para>
|
|
|
|
<para>Start with the PRs that have not been assigned to anyone
|
|
else. If a PR is assigned to someone else, but it looks like
|
|
something you can handle, email the person it is assigned to
|
|
and ask if you can work on it—they might already have a
|
|
patch ready to be tested, or further ideas that you can
|
|
discuss with them.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<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 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
|
|
available for people willing to contribute to the &os;
|
|
project. The list is being regularly updated and contains
|
|
items for both programmers and non-programmers with
|
|
information about each project.</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="contrib-how">
|
|
<title>How to Contribute</title>
|
|
|
|
<para>Contributions to the system generally fall into one or more
|
|
of the following 5 categories:</para>
|
|
|
|
<sect2 xml:id="contrib-general">
|
|
<title>Bug Reports and General Commentary</title>
|
|
|
|
<para>An idea or suggestion of <emphasis>general</emphasis>
|
|
technical interest should be mailed to the &a.hackers;.
|
|
Likewise, people with an interest in such things (and a
|
|
tolerance for a <emphasis>high</emphasis> volume of mail!) may
|
|
subscribe to the &a.hackers;. See <link xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">The
|
|
FreeBSD Handbook</link> for more information about this and
|
|
other mailing lists.</para>
|
|
|
|
<para>If you find a bug or are submitting a specific change,
|
|
please report it using the <link
|
|
xlink:href="https://bugs.FreeBSD.org/submit/">bug submission form</link>.
|
|
Try to fill-in each field of the bug
|
|
report. Unless they exceed 65KB, include any patches directly
|
|
in the report. If the patch is suitable to be applied to the
|
|
source tree put <literal>[PATCH]</literal> in the synopsis of
|
|
the report. When including patches,
|
|
<emphasis>do not</emphasis> use cut-and-paste because
|
|
cut-and-paste turns tabs into spaces and makes them unusable.
|
|
When patches are a lot larger than 20KB, consider compressing
|
|
them (eg. with &man.gzip.1; or &man.bzip2.1;) prior to
|
|
uploading them.</para>
|
|
|
|
<para>After filing a report, you should receive confirmation
|
|
along with a tracking number. Keep this tracking number so
|
|
that you can update us with details about the problem.</para>
|
|
|
|
<para>See also <link xlink:href="&url.articles.problem-reports;/article.html">this
|
|
article</link> on how to write good problem
|
|
reports.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Changes to the Documentation</title>
|
|
|
|
<indexterm>
|
|
<primary>documentation submissions</primary>
|
|
</indexterm>
|
|
|
|
<para>Changes to the documentation are overseen by the &a.doc;.
|
|
Please look at the
|
|
<link xlink:href="&url.books.fdp-primer;/index.html">FreeBSD
|
|
Documentation Project Primer</link> for complete
|
|
instructions. Send submissions and changes (even small ones
|
|
are welcome!) using the same method any other bug
|
|
report.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Changes to Existing Source Code</title>
|
|
|
|
<indexterm><primary>FreeBSD-CURRENT</primary></indexterm>
|
|
|
|
<para>An addition or change to the existing source code is a
|
|
somewhat trickier affair and depends a lot on how far out of
|
|
date you are with the current state of FreeBSD development.
|
|
There is a special on-going release of FreeBSD known as
|
|
<quote>FreeBSD-CURRENT</quote> which is made available in a
|
|
variety of ways for the convenience of developers working
|
|
actively on the system. See <link xlink:href="&url.books.handbook;/current-stable.html">The FreeBSD
|
|
Handbook</link> for more information about getting and
|
|
using FreeBSD-CURRENT.</para>
|
|
|
|
<para>Working from older sources unfortunately means that your
|
|
changes may sometimes be too obsolete or too divergent for
|
|
easy re-integration into FreeBSD. Chances of this can be
|
|
minimized somewhat by subscribing to the &a.announce; and the
|
|
&a.current; lists, where discussions on the current state of
|
|
the system take place.</para>
|
|
|
|
<para>Assuming that you can manage to secure fairly up-to-date
|
|
sources to base your changes on, the next step is to produce a
|
|
set of diffs to send to the FreeBSD maintainers. This is done
|
|
with the &man.diff.1; command.</para>
|
|
|
|
<para>The preferred &man.diff.1; format for submitting patches
|
|
is the unified output format generated by
|
|
<command>diff -u</command>.</para>
|
|
|
|
<indexterm>
|
|
<primary><command>diff</command></primary>
|
|
</indexterm>
|
|
|
|
<screen>&prompt.user; <userinput>diff -u oldfile newfile</userinput></screen>
|
|
|
|
<para>or</para>
|
|
|
|
<screen>&prompt.user; <userinput>diff -u -r -N olddir newdir</userinput></screen>
|
|
|
|
<para>would generate a set of unified diffs for the given source
|
|
file or directory hierarchy.</para>
|
|
|
|
<para>See &man.diff.1; for more information.</para>
|
|
|
|
<para>Once you have a set of diffs (which you may test with the
|
|
&man.patch.1; command), you should submit them for inclusion
|
|
with &os; as a bug report.
|
|
<emphasis>Do not</emphasis> just send the
|
|
diffs to the &a.hackers; or they will get lost! We greatly
|
|
appreciate your submission (this is a volunteer project!);
|
|
because we are busy, we may not be able to address it
|
|
immediately, but it will remain in the PR database until we
|
|
do. Indicate your submission by including
|
|
<literal>[PATCH]</literal> in the synopsis of the
|
|
report.</para>
|
|
|
|
<para>If you feel it appropriate (e.g. you have added, deleted,
|
|
or renamed files), bundle your changes into a
|
|
<command>tar</command> file.
|
|
Archives created with &man.shar.1; are also
|
|
welcome.</para>
|
|
|
|
<para>If your change is of a potentially sensitive nature, such
|
|
as if you are unsure of copyright issues governing its further
|
|
distribution then you should send it to &a.core; directly
|
|
rather than submitting as a bug report. The &a.core;
|
|
reaches a much smaller group of people who do much of the
|
|
day-to-day work on FreeBSD. Note that this group is also
|
|
<emphasis>very busy</emphasis> and so you should only send
|
|
mail to them where it is truly necessary.</para>
|
|
|
|
<para>Please refer to &man.intro.9; and &man.style.9; for
|
|
some information on coding style. We would appreciate it if
|
|
you were at least aware of this information before submitting
|
|
code.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>New Code or Major Value-Added Packages</title>
|
|
|
|
<para>In the case of a significant contribution of a large body
|
|
work, or the addition of an important new feature to FreeBSD,
|
|
it becomes almost always necessary to either send changes as
|
|
tar files or upload them to a web or FTP site for
|
|
other people to access. If you do not have access to a web or
|
|
FTP site, ask on an appropriate FreeBSD mailing list for
|
|
someone to host the changes for you.</para>
|
|
|
|
<para>When working with large amounts of code, the touchy
|
|
subject of copyrights also invariably comes up. &os;
|
|
prefers free software licenses such as BSD or ISC.
|
|
Copyleft licenses such as GPLv2 are sometimes permitted. The
|
|
complete listing can be found on the <link
|
|
xlink:href="&url.base;/internal/software-license.html">core team
|
|
licensing policy</link> page.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Money or Hardware</title>
|
|
|
|
<para>We are always very happy to accept donations to further
|
|
the cause of the FreeBSD Project and, in a volunteer effort
|
|
like ours, a little can go a long way! Donations of hardware
|
|
are also very important to expanding our list of supported
|
|
peripherals since we generally lack the funds to buy such
|
|
items ourselves.</para>
|
|
|
|
<sect3 xml:id="donations">
|
|
<title>Donating Funds</title>
|
|
|
|
<para>The FreeBSD Foundation is a non-profit, tax-exempt
|
|
foundation established to further the goals of the FreeBSD
|
|
Project. As a 501(c)3 entity, the Foundation is generally
|
|
exempt from US federal income tax as well as Colorado State
|
|
income tax. Donations to a tax-exempt entity are often
|
|
deductible from taxable federal income.</para>
|
|
|
|
<para>Donations may be sent in check form to:
|
|
<address>
|
|
The FreeBSD Foundation
|
|
<street>P.O. Box 20247</street>,
|
|
<city>Boulder</city>,
|
|
<state>CO</state> <postcode>80308</postcode>
|
|
<country>USA</country>
|
|
</address></para>
|
|
|
|
<para>The FreeBSD Foundation is now able to accept donations
|
|
through the web with PayPal. To place a donation, please
|
|
visit the Foundation
|
|
<link xlink:href="http://www.freebsdfoundation.org">web
|
|
site</link>.</para>
|
|
|
|
<para>More information about the FreeBSD Foundation can be
|
|
found in <link xlink:href="http://people.FreeBSD.org/~jdp/foundation/announcement.html">The
|
|
FreeBSD Foundation -- an Introduction</link>. To contact
|
|
the Foundation by email, write to
|
|
<email>bod@FreeBSDFoundation.org</email>.</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Donating Hardware</title>
|
|
|
|
<indexterm><primary>donations</primary></indexterm>
|
|
|
|
<para>The FreeBSD Project happily accepts donations of
|
|
hardware that it can find good use for. If you are
|
|
interested in donating hardware, please contact the
|
|
<link xlink:href="&url.base;/donations/">Donations Liaison
|
|
Office</link>.</para>
|
|
</sect3>
|
|
</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 — 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 — 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 and
|
|
<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 — 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 —
|
|
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>
|
|
</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 any more, 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>
|