4604 lines
169 KiB
XML
4604 lines
169 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" [
|
|
<!ENTITY ga "Google Analytics">
|
|
]>
|
|
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
|
|
<info><title>Committer's Guide</title>
|
|
|
|
|
|
<author><orgname>The &os; Documentation Project</orgname></author>
|
|
|
|
<copyright>
|
|
<year>1999</year>
|
|
<year>2000</year>
|
|
<year>2001</year>
|
|
<year>2002</year>
|
|
<year>2003</year>
|
|
<year>2004</year>
|
|
<year>2005</year>
|
|
<year>2006</year>
|
|
<year>2007</year>
|
|
<year>2008</year>
|
|
<year>2009</year>
|
|
<year>2010</year>
|
|
<year>2011</year>
|
|
<year>2012</year>
|
|
<year>2013</year>
|
|
<holder>The &os; Documentation Project</holder>
|
|
</copyright>
|
|
|
|
<legalnotice xml:id="trademarks" role="trademarks">
|
|
&tm-attrib.freebsd;
|
|
&tm-attrib.coverity;
|
|
&tm-attrib.ibm;
|
|
&tm-attrib.intel;
|
|
&tm-attrib.sparc;
|
|
&tm-attrib.general;
|
|
</legalnotice>
|
|
|
|
<pubdate>$FreeBSD$</pubdate>
|
|
|
|
<releaseinfo>$FreeBSD$</releaseinfo>
|
|
|
|
<abstract>
|
|
<para>This document provides information for the &os;
|
|
committer community. All new committers should read this
|
|
document before they start, and existing committers are
|
|
strongly encouraged to review it from time to time.</para>
|
|
|
|
<para>Almost all &os; developers have commit rights to one or
|
|
more repositories. However, a few developers do not, and some
|
|
of the information here applies to them as well. (For
|
|
instance, some people only have rights to work with the
|
|
Problem Report database). Please see <xref linkend="non-committers"/> for more information.</para>
|
|
|
|
<para>This document may also be of interest to members of the
|
|
&os; community who want to learn more about how the project
|
|
works.</para>
|
|
</abstract>
|
|
</info>
|
|
|
|
<sect1 xml:id="admin">
|
|
<title>Administrative Details</title>
|
|
|
|
<informaltable frame="none" orient="port" pgwide="1">
|
|
<tgroup cols="2">
|
|
<colspec colwidth="20*"/>
|
|
<colspec colwidth="80*"/>
|
|
<tbody>
|
|
<row>
|
|
<entry><emphasis>Login Methods</emphasis></entry>
|
|
<entry>&man.ssh.1;, protocol 2 only</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Main Shell Host</emphasis></entry>
|
|
<entry><systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis><literal>src/</literal> Subversion
|
|
Root</emphasis></entry>
|
|
<entry><literal>svn+ssh://</literal><systemitem class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/base</filename>
|
|
(see also <xref linkend="svn-getting-started-base-layout"/>).</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis><literal>doc/</literal> Subversion
|
|
Root</emphasis></entry>
|
|
<entry><literal>svn+ssh://</literal><systemitem class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/doc</filename>
|
|
(see also <xref linkend="svn-getting-started-doc-layout"/>).</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis><literal>ports/</literal> Subversion
|
|
Root</emphasis></entry>
|
|
<entry><literal>svn+ssh://</literal><systemitem class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/ports</filename>
|
|
(see also <xref linkend="svn-getting-started-ports-layout"/>).</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Internal Mailing Lists</emphasis></entry>
|
|
<entry>developers (technically called all-developers),
|
|
doc-developers, doc-committers, ports-developers,
|
|
ports-committers, src-developers, src-committers. (Each
|
|
project repository has its own -developers and
|
|
-committers mailing lists. Archives for these lists may
|
|
be found in files
|
|
<filename>/home/mail/repository-name-developers-archive</filename>
|
|
and
|
|
<filename>/home/mail/repository-name-committers-archive</filename>
|
|
on the <systemitem class="fqdomainname">FreeBSD.org</systemitem>
|
|
cluster.)</entry>
|
|
</row>
|
|
|
|
|
|
<row>
|
|
<entry><emphasis>Core Team monthly
|
|
reports</emphasis></entry>
|
|
<entry><filename>/home/core/public/monthly-reports</filename>
|
|
on the <systemitem class="fqdomainname">FreeBSD.org</systemitem>
|
|
cluster.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Ports Management Team monthly
|
|
reports</emphasis></entry>
|
|
<entry><filename>/home/portmgr/public/monthly-reports</filename>
|
|
on the <systemitem class="fqdomainname">FreeBSD.org</systemitem>
|
|
cluster.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Noteworthy <literal>src/</literal> SVN
|
|
Branches</emphasis></entry>
|
|
<entry>
|
|
<literal>stable/8</literal> (8.X-STABLE),
|
|
<literal>stable/9</literal> (9.X-STABLE),
|
|
<literal>stable/10</literal> (10.X-STABLE),
|
|
<literal>head</literal> (-CURRENT)</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>&man.ssh.1; is required to connect to the project hosts.
|
|
For more information, see <xref linkend="ssh.guide"/>.</para>
|
|
|
|
<para>Useful links:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><link xlink:href="&url.base;/internal/">&os;
|
|
Project Internal Pages</link></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><link xlink:href="&url.base;/internal/machines.html">&os; Project
|
|
Hosts</link></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><link xlink:href="&url.base;/administration.html">&os; Project
|
|
Administrative Groups</link></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="committer.types">
|
|
<title>Commit Bit Types</title>
|
|
|
|
<para>The &os; repository has a number of components which,
|
|
when combined, support the basic operating system source,
|
|
documentation, third party application ports infrastructure, and
|
|
various maintained utilities. When &os; commit bits are
|
|
allocated, the areas of the tree where the bit may be used are
|
|
specified. Generally, the areas associated with a bit reflect
|
|
who authorized the allocation of the commit bit. Additional
|
|
areas of authority may be added at a later date: when this
|
|
occurs, the committer should follow normal commit bit allocation
|
|
procedures for that area of the tree, seeking approval from the
|
|
appropriate entity and possibly getting a mentor for that area
|
|
for some period of time.</para>
|
|
|
|
<informaltable frame="none" pgwide="1">
|
|
<tgroup cols="3">
|
|
<tbody>
|
|
<row>
|
|
<entry><emphasis>Committer Type</emphasis></entry>
|
|
<entry><emphasis>Responsible</emphasis></entry>
|
|
<entry><emphasis>Tree Components</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>src</entry>
|
|
<entry>core@</entry>
|
|
<entry>src/, doc/ subject to appropriate review</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>doc</entry>
|
|
<entry>doceng@</entry>
|
|
<entry>doc/, src/ documentation</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>ports</entry>
|
|
<entry>portmgr@</entry>
|
|
<entry>ports/</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>Commit bits allocated prior to the development of the notion
|
|
of areas of authority may be appropriate for use in many parts
|
|
of the tree. However, common sense dictates that a committer
|
|
who has not previously worked in an area of the tree seek review
|
|
prior to committing, seek approval from the appropriate
|
|
responsible party, and/or work with a mentor. Since the rules
|
|
regarding code maintenance differ by area of the tree, this is
|
|
as much for the benefit of the committer working in an area of
|
|
less familiarity as it is for others working on the tree.</para>
|
|
|
|
<para>Committers are encouraged to seek review for their work as
|
|
part of the normal development process, regardless of the area
|
|
of the tree where the work is occurring.</para>
|
|
|
|
<sect2>
|
|
<title>Policy for <filename>doc/</filename> Committer Activity
|
|
in <filename>src/</filename></title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>doc committers may commit documentation changes to src
|
|
files, such as man pages, READMEs, fortune databases,
|
|
calendar files, and comment fixes without approval from a
|
|
src committer, subject to the normal care and tending of
|
|
commits.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>doc committers may commit minor src changes and fixes,
|
|
such as build fixes, small features, etc, with an
|
|
"Approved by" from a src committer.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>doc committers may seek an upgrade to a src commit bit
|
|
by acquiring a mentor, who will propose the doc committer
|
|
to core. When approved, they will be added to 'access'
|
|
and the normal mentoring period will ensue, which will
|
|
involve a continuing of <quote>Approved by</quote> for
|
|
some period.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>"Approved by" is only acceptable from non-mentored src
|
|
committers -- mentored committers can provide a "Reviewed
|
|
by" but not an "Approved by".</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="subversion-primer">
|
|
<title>Subversion Primer</title>
|
|
|
|
<para>It is assumed that you are already familiar with the basic
|
|
operation of the version control systems in use. Traditionally
|
|
this was CVS. Subversion is used for the <literal>src</literal>
|
|
tree as of May 2008, the <literal>doc/www</literal> tree as of
|
|
May 2012 and the <literal>ports</literal> tree as of July
|
|
2012.</para>
|
|
|
|
<para><link xlink:href="http://wiki.freebsd.org/SubversionMissing">There
|
|
is a list of things missing in Subversion when compared to
|
|
CVS</link>. The notes at <uri xlink:href="http://people.freebsd.org/~peter/svn_notes.txt">http://people.freebsd.org/~peter/svn_notes.txt</uri>
|
|
might also be useful.</para>
|
|
|
|
<sect2 xml:id="svn-intro">
|
|
<title>Introduction</title>
|
|
|
|
<para>The &os; source repository switched from
|
|
<acronym>CVS</acronym> to Subversion on May 31st, 2008. The
|
|
first real <acronym>SVN</acronym> commit is
|
|
<emphasis>r179447</emphasis>.</para>
|
|
|
|
<para>The &os; <literal>doc/www</literal> repository switched
|
|
from <acronym>CVS</acronym> to Subversion on May 19th, 2012.
|
|
The first real <acronym>SVN</acronym> commit is
|
|
<emphasis>r38821</emphasis>.</para>
|
|
|
|
<note>
|
|
<para>Part of the <literal>doc/www</literal>
|
|
<acronym>CVS</acronym> to <acronym>SVN</acronym> conversion
|
|
included an infrastructural change to the build process.
|
|
The most notable change is the location of the
|
|
&os; website <literal>www</literal> tree, which has
|
|
been moved from
|
|
<literal>www/lang/</literal> to
|
|
<literal>head/lang/htdocs/</literal>.</para>
|
|
</note>
|
|
|
|
<para>The &os; <literal>ports</literal> repository switched
|
|
from <acronym>CVS</acronym> to Subversion on July 14th, 2012.
|
|
The first real <acronym>SVN</acronym> commit is
|
|
<emphasis>r300894</emphasis>.</para>
|
|
|
|
<para>There are mechanisms in place to automatically merge
|
|
changes back from the Subversion <literal>src</literal>
|
|
repository to the <acronym>CVS</acronym> repository for
|
|
some &os; branches (<literal>releng/6</literal> through
|
|
<literal>releng/9</literal>), however this is purely to
|
|
support pre-existing end-user installs and should not be
|
|
relied upon, recommended or advertised. Future branches
|
|
will not be exported to CVS at all. The
|
|
<literal>ports</literal> repository was exported to CVS
|
|
for a period of time to aid end user migration, but as of
|
|
28th February 2013 is no longer exported.</para>
|
|
|
|
<para>Subversion is not that different from
|
|
<acronym>CVS</acronym> when it comes to daily use, but there
|
|
are differences. Subversion has a number of features that
|
|
should make developers' lives easier. The most important
|
|
advantage to Subversion (and the reason why &os; switched) is
|
|
that it handles branches and merging much better than CVS
|
|
does. Some of the principal differences are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Commits are atomic.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Revision numbers apply across the repository—all
|
|
files that were modified in the same commit have the same
|
|
revision number.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Branching and tagging are namespace operations.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Directories are versioned.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Files and directories can have arbitrary, versioned
|
|
metadata attached to them.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Files and directories can be copied, with full history
|
|
tracking.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>No more contortions due to <acronym>CVS</acronym>
|
|
weakness such as applying &man.patch.1; files at compile
|
|
time in order to avoid touching vendor branch code.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>No more repo-copies.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Subversion can be installed from the &os; Ports
|
|
Collection by issuing these commands:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd /usr/ports/devel/subversion</userinput>
|
|
&prompt.root; <userinput>make clean install</userinput></screen>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="svn-getting-started">
|
|
<title>Getting Started</title>
|
|
|
|
<para>There are a few ways to obtain a working copy of the tree
|
|
from Subversion. This section will explain them.</para>
|
|
|
|
<sect3 xml:id="svn-getting-started-direct-checkout">
|
|
<title>Direct Checkout</title>
|
|
|
|
<para>The first is to check out directly from the main
|
|
repository. For the <literal>src</literal> tree,
|
|
use:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/base/head /usr/src</userinput></screen>
|
|
|
|
<para>For the <literal>doc</literal> tree, use:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/doc/head /usr/doc</userinput></screen>
|
|
|
|
<para>For the <literal>ports</literal> tree, use:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/ports/head /usr/ports</userinput></screen>
|
|
|
|
<note>
|
|
<para>Though the remaining examples in this document are
|
|
written with the workflow of working with the
|
|
<literal>src</literal> tree in mind, the underlying
|
|
concepts are the same for working with the
|
|
<literal>doc</literal> and the <literal>ports</literal>
|
|
tree.
|
|
Ports related Subversion operations are listed in
|
|
<xref linkend="ports"/>.</para>
|
|
</note>
|
|
|
|
<para>The above command will check out a
|
|
<literal>CURRENT</literal> source tree as <filename>/usr/src/</filename>,
|
|
which can be any target directory on the local filesystem.
|
|
Omitting the final argument of that command causes the
|
|
working copy, in this case, to be named <quote>head</quote>,
|
|
but that can be renamed safely.</para>
|
|
|
|
<para><literal>svn+ssh</literal> means the
|
|
<acronym>SVN</acronym> protocol tunnelled over
|
|
<acronym>SSH</acronym>. The name of the server is
|
|
<literal>svn.freebsd.org</literal>, <literal>base</literal>
|
|
is the path to the repository, and <literal>head</literal>
|
|
is the subdirectory within the repository.</para>
|
|
|
|
<para>If your &os; login name is different from your login
|
|
name on your local machine, you must either include it in
|
|
the <acronym>URL</acronym> (for example
|
|
<literal>svn+ssh://jarjar@svn.freebsd.org/base/head</literal>),
|
|
or add an entry to your <filename>~/.ssh/config</filename>
|
|
in the form:</para>
|
|
|
|
<programlisting>Host svn.freebsd.org
|
|
User jarjar</programlisting>
|
|
|
|
<para>This is the simplest method, but it's hard to tell just
|
|
yet how much load it will place on the repository.
|
|
Subversion is much faster than <acronym>CVS</acronym>,
|
|
however.</para>
|
|
|
|
<note>
|
|
<para>The <command>svn diff</command> does not require
|
|
access to the server as <acronym>SVN</acronym> stores a
|
|
reference copy of every file in the working copy. This,
|
|
however, means that Subversion working copies are very
|
|
large in size.</para>
|
|
</note>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-getting-started-checkout-from-a-mirror">
|
|
<title>Checkout from a Mirror</title>
|
|
|
|
<para>Check out a working copy from a mirror by
|
|
substituting the mirror's <acronym>URL</acronym> for
|
|
<literal>svn+ssh://svn.freebsd.org/base</literal>. This can
|
|
be an official mirror or a mirror maintained by
|
|
using <command>svnsync</command>.</para>
|
|
|
|
<para>There is a serious disadvantage to this method: every
|
|
time something is to be committed, a
|
|
<command>svn relocate</command> to the master repository has
|
|
to be done, remembering to <command>svn relocate</command>
|
|
back to the mirror after the commit. Also, since
|
|
<command>svn relocate</command> only works between
|
|
repositories that have the same UUID, some hacking of the
|
|
local repository's UUID has to occur before it is possible
|
|
to start using it.</para>
|
|
|
|
<para>Unlike with <acronym>CVS</acronym>,
|
|
the hassle of a local
|
|
<command>svnsync</command> mirror probably is not worth it
|
|
unless the network connectivity situation or other factors
|
|
demand it. If it is needed, see the end of this chapter for
|
|
information on how to set one up.</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-getting-started-base-layout">
|
|
<title><literal>RELENG_*</literal> Branches and General
|
|
Layout</title>
|
|
|
|
<para>In <literal>svn+ssh://svn.freebsd.org/base</literal>,
|
|
<emphasis>base</emphasis> refers to the source tree.
|
|
Similarly, <emphasis>ports</emphasis> refers to the ports
|
|
tree, and so on. These are separate repositories with their
|
|
own change number sequences, access controls and commit
|
|
mail.</para>
|
|
|
|
<para>For the base repository, HEAD refers to the -CURRENT
|
|
tree. For example, <filename>head/bin/ls</filename> is what
|
|
would go into <filename>/usr/src/bin/ls</filename> in a
|
|
release. Some key locations are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>/head/</emphasis> which corresponds to
|
|
<literal>HEAD</literal>, also known as
|
|
<literal>-CURRENT</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>/stable/<replaceable>n</replaceable></emphasis>
|
|
which corresponds to
|
|
<literal>RELENG_n</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>/releng/<replaceable>n.n</replaceable></emphasis>
|
|
which corresponds to
|
|
<literal>RELENG_n_n</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>/release/<replaceable>n.n.n</replaceable></emphasis>
|
|
which corresponds to
|
|
<literal>RELENG_n_n_n_RELEASE</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>/vendor*</emphasis> is the vendor branch
|
|
import work area. This directory itself does not
|
|
contain branches, however its subdirectories do. This
|
|
contrasts with the <emphasis>stable</emphasis>,
|
|
<emphasis>releng</emphasis> and
|
|
<emphasis>release</emphasis> directories.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>/projects</emphasis> and
|
|
<emphasis>/user</emphasis> feature a branch work area,
|
|
like in Perforce. As above, the
|
|
<emphasis>/user</emphasis> directory does not contain
|
|
branches itself.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-getting-started-doc-layout">
|
|
<title>&os; Documentation Project Branches and
|
|
Layout</title>
|
|
|
|
<para>In <literal>svn+ssh://svn.freebsd.org/doc</literal>,
|
|
<emphasis>doc</emphasis> refers to the repository root of
|
|
the source tree.</para>
|
|
|
|
<para>In general, most &os; Documentation Project work will be
|
|
done within the <filename>head/</filename> branch of the
|
|
documentation source tree.</para>
|
|
|
|
<para>&os; documentation is written and/or translated to
|
|
various languages, each in a separate
|
|
directory in the <filename>head/</filename>
|
|
branch.</para>
|
|
|
|
<para>Each translation set contains several subdirectories for
|
|
the various parts of the &os; Documentation Project. A few
|
|
noteworthy directories are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>/articles/</emphasis> contains the source
|
|
code for articles written by various &os;
|
|
contributors.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>/books/</emphasis> contains the source
|
|
code for the different books, such as the
|
|
&os; Handbook.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>/htdocs/</emphasis> contains the source
|
|
code for the &os; website.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-getting-started-ports-layout">
|
|
<title>&os; Ports Tree Branches and Layout</title>
|
|
|
|
<para>In <literal>svn+ssh://svn.freebsd.org/ports</literal>,
|
|
<emphasis>ports</emphasis> refers to the repository root of the
|
|
ports tree.</para>
|
|
|
|
<para>In general, most &os; port work will be done within
|
|
the <filename>head/</filename> branch of the ports tree
|
|
which is the actual ports tree used to install software.
|
|
Some other key locations are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>/branches/RELENG_<replaceable>n_n_n</replaceable></emphasis>
|
|
which corresponds to
|
|
<literal>RELENG_n_n_n</literal>
|
|
is used to merge back security updates in preparation
|
|
for a release.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>/tags/RELEASE_<replaceable>n_n_n</replaceable></emphasis>
|
|
which corresponds to
|
|
<literal>RELEASE_n_n_n</literal>
|
|
represents a release tag of the ports tree.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>/tags/RELEASE_<replaceable>n</replaceable>_EOL</emphasis>
|
|
represents the end of life tag of a specific &os;
|
|
branch.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="svn-daily-use">
|
|
<title>Daily Use</title>
|
|
|
|
<para>This section will explain how to perform common day-to-day
|
|
operations with Subversion.</para>
|
|
|
|
<sect3 xml:id="svn-daily-use-help">
|
|
<title>Help</title>
|
|
|
|
<para><acronym>SVN</acronym> has built in help documentation.
|
|
It can be accessed by typing the following command:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn help</userinput></screen>
|
|
|
|
<para>Additional information can be found in the
|
|
<link xlink:href="http://svnbook.red-bean.com/">Subversion
|
|
Book</link>.</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-daily-use-checkout">
|
|
<title>Checkout</title>
|
|
|
|
<para>As seen earlier, to check out the &os; head
|
|
branch:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/base/head /usr/src</userinput></screen>
|
|
|
|
<para>At some point, more than just <literal>HEAD</literal>
|
|
will probably be useful, for instance when merging changes
|
|
to stable/7. Therefore, it may be useful to have a partial
|
|
checkout of the complete tree (a full checkout would be very
|
|
painful).</para>
|
|
|
|
<para>To do this, first check out the root of the
|
|
repository:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn checkout --depth=immediates svn+ssh://svn.freebsd.org/base</userinput></screen>
|
|
|
|
<para>This will give <literal>base</literal> with all the
|
|
files it contains (at the time of writing, just
|
|
<filename>ROADMAP.txt</filename>) and empty subdirectories
|
|
for <literal>head</literal>, <literal>stable</literal>,
|
|
<literal>vendor</literal> and so on.</para>
|
|
|
|
<para>Expanding the working copy is possible. Just change the
|
|
depth of the various subdirectories:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn up --set-depth=infinity base/head</userinput>
|
|
&prompt.user; <userinput>svn up --set-depth=immediates base/release base/releng base/stable</userinput></screen>
|
|
|
|
<para>The above command will pull down a full copy of
|
|
<literal>head</literal>, plus empty copies of every
|
|
<literal>release</literal> tag, every
|
|
<literal>releng</literal> branch, and every
|
|
<literal>stable</literal> branch.</para>
|
|
|
|
<para>If at a later date merging to
|
|
<literal>7-STABLE</literal> is required, expand the working
|
|
copy:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn up --set-depth=infinity base/stable/7</userinput></screen>
|
|
|
|
<para>Subtrees do not have to be expanded completely. For
|
|
instance, expanding only <literal>stable/7/sys</literal> and
|
|
then later expand the rest of
|
|
<literal>stable/7</literal>:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn up --set-depth=infinity base/stable/7/sys</userinput>
|
|
&prompt.user; <userinput>svn up --set-depth=infinity base/stable/7</userinput></screen>
|
|
|
|
<para>Updating the tree with <command>svn update</command>
|
|
will only update what was previously asked for (in this
|
|
case, <literal>head</literal> and
|
|
<literal>stable/7</literal>; it will not pull down the whole
|
|
tree.</para>
|
|
|
|
<note>
|
|
<para>Decreasing the depth of a working copy is not
|
|
possible.</para>
|
|
</note>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-daily-use-anonymous-checkout">
|
|
<title>Anonymous Checkout</title>
|
|
|
|
<para>It is possible to anonymously check out the &os;
|
|
repository with Subversion. This will give access to a
|
|
read-only tree that can be updated, but not committed back
|
|
to the main repository. To do this, use the following command:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn co https://svn0.us-west.FreeBSD.org/base/head /usr/src</userinput></screen>
|
|
|
|
<para>Select the closest mirror and verify the mirror server
|
|
certificate from the list of <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion
|
|
mirror sites</link>.</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-daily-use-updating-the-tree">
|
|
<title>Updating the Tree</title>
|
|
|
|
<para>To update a working copy to either the latest revision,
|
|
or a specific revision:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn update</userinput>
|
|
&prompt.user; <userinput>svn update -r12345</userinput></screen>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-daily-use-status">
|
|
<title>Status</title>
|
|
|
|
<para>To view the local changes that have been made to the
|
|
working copy:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn status</userinput></screen>
|
|
|
|
<para>To show local changes and files that are out-of-date
|
|
do:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn status --show-updates</userinput></screen>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-daily-use-editing-and-committing">
|
|
<title>Editing and Committing</title>
|
|
|
|
<para>Unlike Perforce, <acronym>SVN</acronym> does not need to
|
|
be told in advance about file editing.</para>
|
|
|
|
<para><command>svn commit</command> works like the equivalent
|
|
<acronym>CVS</acronym> command. To commit all changes in
|
|
the current directory and all subdirectories:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn commit</userinput></screen>
|
|
|
|
<para>To commit all changes in, for example, <filename>lib/libfetch/</filename>
|
|
and <filename>usr/bin/fetch/</filename>
|
|
in a single operation:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn commit lib/libfetch usr/bin/fetch</userinput></screen>
|
|
|
|
<para>There is also a commit wrapper for the ports tree to
|
|
handle the properties and sanity checking your
|
|
changes:</para>
|
|
|
|
<screen>&prompt.user; <userinput>/usr/ports/Tools/scripts/psvn commit
|
|
</userinput></screen>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-daily-use-adding-and-removing">
|
|
<title>Adding and Removing Files</title>
|
|
|
|
<note>
|
|
<para>Before adding files, get a copy of <link xlink:href="http://people.freebsd.org/~peter/auto-props.txt">auto-props.txt</link>
|
|
(there is also a <link xlink:href="http://people.freebsd.org/~beat/cvs2svn/auto-props.txt">
|
|
ports tree specific version</link>)
|
|
and add it to <filename>~/.subversion/config</filename>
|
|
according to the instructions in the file. If you added
|
|
something before reading this, use
|
|
<command>svn rm --keep-local</command> for just added
|
|
files, fix your config file and re-add them again. The
|
|
initial config file is created when you first run a svn
|
|
command, even something as simple as
|
|
<command>svn help</command>.</para>
|
|
</note>
|
|
|
|
<para>Files are added to a
|
|
<acronym>SVN</acronym> repository with <command>svn
|
|
add</command>. To add a file named
|
|
<emphasis>foo</emphasis>, edit it, then:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn add foo</userinput></screen>
|
|
|
|
<note>
|
|
<para>Most new source files should include a
|
|
<literal>$&os;$</literal> string near the start of the
|
|
file. On commit, <command>svn</command> will expand
|
|
the <literal>$&os;$</literal> string,
|
|
adding the file path, revision number, date and time of
|
|
commit, and the username of the committer. Files which
|
|
cannot be modified may be committed without the
|
|
<literal>$&os;$</literal> string.</para>
|
|
</note>
|
|
|
|
<para>Files can be removed with <command>svn
|
|
remove</command>:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn remove foo</userinput></screen>
|
|
|
|
<para>Subversion does not require deleting the file before
|
|
using <command>svn rm</command>, and indeed complains if
|
|
that happens.</para>
|
|
|
|
<para>It is possible to add directories with
|
|
<command>svn add</command>:</para>
|
|
|
|
<screen>&prompt.user; <userinput>mkdir bar</userinput>
|
|
&prompt.user; <userinput>svn add bar</userinput></screen>
|
|
|
|
<para>Although <command>svn mkdir</command> makes this easier
|
|
by combining the creation of the directory and the adding of
|
|
it:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn mkdir bar</userinput></screen>
|
|
|
|
<para>Like files, directories are removed with
|
|
<command>svn rm</command>. There is no separate command
|
|
specifically for removing directories.</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn rm bar</userinput></screen>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-daily-use-copying-and-moving">
|
|
<title>Copying and Moving Files</title>
|
|
|
|
<para>This command creates a copy of
|
|
<filename>foo.c</filename> named <filename>bar.c</filename>,
|
|
with the new file also under version control:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn copy foo.c bar.c</userinput></screen>
|
|
|
|
<para>The example above is equivalent to:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cp foo.c bar.c</userinput>
|
|
&prompt.user; <userinput>svn add bar.c</userinput></screen>
|
|
|
|
<para>To move and rename a file:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn move foo.c bar.c</userinput></screen>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-daily-use-log-and-annotate">
|
|
<title>Log and Annotate</title>
|
|
|
|
<para><command>svn log</command> shows revisions and commit
|
|
messages, most recent first, for files or directories. When
|
|
used on a directory, all revisions that affected the
|
|
directory and files within that directory are shown.</para>
|
|
|
|
<para><command>svn annotate</command>, or equally <command>svn
|
|
praise</command> or <command>svn blame</command>, shows
|
|
the most recent revision number and who committed that
|
|
revision for each line of a file.</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-daily-use-diffs">
|
|
<title>Diffs</title>
|
|
|
|
<para><command>svn diff</command> displays changes to the
|
|
working copy. Diffs generated by <acronym>SVN</acronym> are
|
|
unified and include new files by default in the diff
|
|
output.</para>
|
|
|
|
<para><command>svn diff</command> can show the changes between
|
|
two revisions of the same file:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn diff -r179453:179454 ROADMAP.txt</userinput></screen>
|
|
|
|
<para>It can also show all changes for a specific changeset.
|
|
The following will show what changes were made to the
|
|
current directory and all subdirectories in changeset
|
|
179454:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn diff -c179454 .</userinput></screen>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-daily-use-reverting">
|
|
<title>Reverting</title>
|
|
|
|
<para>Local changes (including additions and deletions) can be
|
|
reverted using <command>svn revert</command>. It does not
|
|
update out-of-date files, but just replaces them with
|
|
pristine copies of the original version.</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-daily-use-conflicts">
|
|
<title>Conflicts</title>
|
|
|
|
<para>If an <command>svn update</command> resulted in a merge
|
|
conflict, Subversion will remember which files have
|
|
conflicts and refuse to commit any changes to those files
|
|
until explicitly told that the conflicts have been resolved.
|
|
The simple, not yet deprecated procedure is the
|
|
following:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn resolved foo</userinput></screen>
|
|
|
|
<para>However, the preferred procedure is:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn resolve --accept=working foo</userinput></screen>
|
|
|
|
<para>The two examples are equivalent. Possible values for
|
|
<literal>--accept</literal> are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>working</literal>: use the version in your
|
|
working directory (which one presumes has been edited to
|
|
resolve the conflicts).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>base</literal>: use a pristine copy of the
|
|
version you had before <command>svn update</command>,
|
|
discarding your own changes, the conflicting changes,
|
|
and possibly other intervening changes as well.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>mine-full</literal>: use what you had
|
|
before <command>svn update</command>, including your own
|
|
changes, but discarding the conflicting changes, and
|
|
possibly other intervening changes as well.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>theirs-full</literal>: use the version that
|
|
was retrieved when you did
|
|
<command>svn update</command>, discarding your own
|
|
changes.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Advanced Use</title>
|
|
|
|
<sect3 xml:id="svn-advanced-use-sparse-checkouts">
|
|
<title>Sparse Checkouts</title>
|
|
|
|
<para><acronym>SVN</acronym> allows
|
|
<emphasis>sparse</emphasis>, or partial checkouts of a
|
|
directory by adding <option>--depth</option> to a
|
|
<command>svn checkout</command>.</para>
|
|
|
|
<para>Valid arguments to <option>--depth</option>
|
|
are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>empty</literal>: the directory itself
|
|
without any of its contents.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>files</literal>: the directory and any
|
|
files it contains.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>immediates</literal>: the directory and any
|
|
files and directories it contains, but none of the
|
|
subdirectories' contents.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>infinity</literal>: anything.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>The <literal>--depth</literal> option applies to many
|
|
other commands, including <command>svn commit</command>,
|
|
<command>svn revert</command>, and <command>svn
|
|
diff</command>.</para>
|
|
|
|
<para>Since <literal>--depth</literal> is sticky, there is a
|
|
<literal>--set-depth</literal> option for <command>svn
|
|
update</command> that will change the selected depth.
|
|
Thus, given the working copy produced by the previous
|
|
example:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cd ~/freebsd</userinput>
|
|
&prompt.user; <userinput>svn update --set-depth=immediates .</userinput></screen>
|
|
|
|
<para>The above command will populate the working copy in
|
|
<replaceable>~/freebsd</replaceable> with
|
|
<filename>ROADMAP.txt</filename> and empty subdirectories,
|
|
and nothing will happen when <command>svn update</command>
|
|
is executed on the subdirectories. However, the following
|
|
command will set the depth for
|
|
<replaceable>head</replaceable> (in this case) to infinity,
|
|
and fully populate it:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn update --set-depth=infinity head</userinput></screen>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-advanced-use-direct-operation">
|
|
<title>Direct Operation</title>
|
|
|
|
<para>Certain operations can be performed directly on the
|
|
repository without touching the working copy. Specifically,
|
|
this applies to any operation that does not require editing
|
|
a file, including:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>log</literal>,
|
|
<literal>diff</literal></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>mkdir</literal></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>remove</literal>, <literal>copy</literal>,
|
|
<literal>rename</literal></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>propset</literal>,
|
|
<literal>propedit</literal>,
|
|
<literal>propdel</literal></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>merge</literal></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Branching is very fast. The following command would be
|
|
used to branch <literal>RELENG_8</literal>:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn copy svn+ssh://svn.freebsd.org/base/head svn+ssh://svn.freebsd.org/base/stable/8</userinput></screen>
|
|
|
|
<para>This is equivalent to the following set of commands
|
|
which take minutes and hours as opposed to seconds,
|
|
depending on your network connection:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn checkout --depth=immediates svn+ssh://svn.freebsd.org/base</userinput>
|
|
&prompt.user; <userinput>cd base</userinput>
|
|
&prompt.user; <userinput>svn update --depth=infinity head</userinput>
|
|
&prompt.user; <userinput>svn copy head stable/8</userinput>
|
|
&prompt.user; <userinput>svn commit stable/8</userinput></screen>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-advanced-use-merging">
|
|
<title>Merging with <acronym>SVN</acronym></title>
|
|
|
|
<para>This section deals with merging code from one branch to
|
|
another (typically, from head to a stable branch).</para>
|
|
|
|
<note>
|
|
<para>In all examples below, <literal>$FSVN</literal>
|
|
refers to the location of the &os; Subversion repository,
|
|
<literal>svn+ssh://svn.freebsd.org/base/</literal>.</para>
|
|
</note>
|
|
|
|
<sect4>
|
|
<title>About Merge Tracking</title>
|
|
|
|
<para>From the user's perspective, merge tracking
|
|
information (or mergeinfo) is stored in a property called
|
|
<literal>svn:mergeinfo</literal>, which is a
|
|
comma-separated list of revisions and ranges of revisions
|
|
that have been merged. When set on a file, it applies
|
|
only to that file. When set on a directory, it applies to
|
|
that directory and its descendants (files and directories)
|
|
except for those that have their own
|
|
<literal>svn:mergeinfo</literal>.</para>
|
|
|
|
<para>It is <emphasis>not</emphasis> inherited. For
|
|
instance, <filename>stable/6/contrib/openpam/</filename>
|
|
does not implicitly inherit mergeinfo from
|
|
<filename>stable/6/</filename>, or
|
|
<filename>stable/6/contrib/</filename>.
|
|
Doing so would make partial checkouts very hard to manage.
|
|
Instead, mergeinfo is explicitly propagated down the tree.
|
|
For merging something into
|
|
<filename>branch/foo/bar/</filename>,
|
|
the following rules apply:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>If
|
|
<filename>branch/foo/bar/</filename>
|
|
does not already have a mergeinfo record, but a direct
|
|
ancestor (for instance,
|
|
<filename>branch/foo/</filename>)
|
|
does, then that record will be propagated down to
|
|
<filename>branch/foo/bar/</filename>
|
|
before information about the current merge is
|
|
recorded.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Information about the current merge will
|
|
<emphasis>not</emphasis> be propagated back up that
|
|
ancestor.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If a direct descendant of
|
|
<filename>branch/foo/bar/</filename>
|
|
(for instance, <filename>branch/foo/bar/baz/</filename>)
|
|
already has a mergeinfo record, information about the
|
|
current merge will be propagated down to it.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>If you consider the case where a revision changes
|
|
several separate parts of the tree (for example, <filename>branch/foo/bar/</filename> and
|
|
<filename>branch/foo/quux/</filename>),
|
|
but you only want to merge some of it (for example,
|
|
<filename>branch/foo/bar/</filename>),
|
|
you will see that these rules make sense. If mergeinfo
|
|
was propagated up, it would seem like that revision had
|
|
also been merged to <filename>branch/foo/quux/</filename>, when in
|
|
fact it had not been.</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>Selecting the Source and Target</title>
|
|
|
|
<para>Because of mergeinfo propagation, it is important to
|
|
choose the source and target for the merge carefully to
|
|
minimise property changes on unrelated directories.</para>
|
|
|
|
<para>The rules for selecting the merge target (the
|
|
directory that you will merge the changes to) can be
|
|
summarized as follows:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Never merge directly to a file.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Never, ever merge directly to a file.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Never, ever, ever</emphasis> merge
|
|
directly to a file.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes to kernel code should be merged to
|
|
<filename>sys/</filename>. For
|
|
instance, a change to the &man.ichwd.4; driver should
|
|
be merged to
|
|
|
|
<filename>sys/</filename>, not
|
|
<filename>sys/dev/ichwd/</filename>.
|
|
Likewise, a change to the TCP/IP stack should be
|
|
merged to <filename>sys/</filename>,
|
|
not <filename>sys/netinet/</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes to code under
|
|
<filename>etc/</filename> should be
|
|
merged at <filename>etc/</filename>,
|
|
not below it.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes to vendor code (code in
|
|
|
|
<filename>contrib/</filename>,
|
|
<filename>crypto/</filename> and so
|
|
on) should be merged to the directory where vendor
|
|
imports happen. For instance, a change to <filename>crypto/openssl/util/</filename>
|
|
should be merged to <filename>crypto/openssl/</filename>. This
|
|
is rarely an issue, however, since changes to vendor
|
|
code are usually merged wholesale.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes to userland programs should as a general
|
|
rule be merged to the directory that contains the
|
|
Makefile for that program. For instance, a change to
|
|
<filename>usr.bin/xlint/arch/i386/</filename>
|
|
should be merged to <filename>usr.bin/xlint/</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes to userland libraries should as a general
|
|
rule be merged to the directory that contains the
|
|
Makefile for that library. For instance, a change to
|
|
<filename>lib/libc/gen/</filename>
|
|
should be merged to <filename>lib/libc/</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>There may be cases where it makes sense to deviate
|
|
from the rules for userland programs and libraries.
|
|
For instance, everything under <filename>lib/libpam/</filename> is merged
|
|
to <filename>lib/libpam/</filename>,
|
|
even though the library itself and all of the modules
|
|
each have their own Makefile.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes to manual pages should be merged to
|
|
<filename>share/man/manN/</filename>,
|
|
for the appropriate value of
|
|
<literal>N</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Other changes to
|
|
<filename>share/</filename> should
|
|
be merged to the appropriate subdirectory and not to
|
|
<filename>share/</filename>
|
|
directly.</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes to a top-level file in the source tree
|
|
such as <filename>UPDATING</filename> or
|
|
<filename>Makefile.inc1</filename> should be merged
|
|
directly to that file rather than to the root of the
|
|
whole tree. Yes, this is an exception to the first
|
|
three rules.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When in doubt, ask.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>If you need to merge changes to several places at once
|
|
(for instance, changing a kernel interface and every
|
|
userland program that uses it), merge each target
|
|
separately, then commit them together. For instance, if
|
|
you merge a revision that changed a kernel
|
|
<acronym>API</acronym> and updated all the userland bits
|
|
that used that <acronym>API</acronym>, you would merge the
|
|
kernel change to sys, and the userland bits to the
|
|
appropriate userland directories, then commit all of these
|
|
in one go.</para>
|
|
|
|
<para>The source will almost invariably be the same as the
|
|
target. For instance, you will always merge <filename>stable/7/lib/libc/</filename> from
|
|
<filename>head/lib/libc/</filename>.
|
|
The only exception would be when merging changes to code
|
|
that has moved in the source branch but not in the parent
|
|
branch. For instance, a change to &man.pkill.1; would be
|
|
merged from <filename>bin/pkill/</filename> in head to
|
|
<filename>usr.bin/pkill/</filename> in
|
|
stable/7.</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>Preparing the Merge Target</title>
|
|
|
|
<para>Because of the mergeinfo propagation issues described
|
|
earlier, it is very important that you never merge changes
|
|
into a sparse working copy. You must always have a full
|
|
checkout of the branch you will merge into. For instance,
|
|
when merging from HEAD to 7, you must have a full checkout
|
|
of stable/7:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cd stable/7</userinput>
|
|
&prompt.user; <userinput>svn up --set-depth=infinity</userinput></screen>
|
|
|
|
<para>The target directory must also be up-to-date and must
|
|
not contain any uncommitted changes or stray files.</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>Identifying Revisions</title>
|
|
|
|
<para>Identifying revisions to be merged is a must. If the
|
|
target already has complete mergeinfo, ask
|
|
<acronym>SVN</acronym> for a list:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cd stable/6/contrib/openpam</userinput>
|
|
&prompt.user; <userinput>svn mergeinfo --show-revs=eligible $FSVN/head/contrib/openpam</userinput></screen>
|
|
|
|
<para>If the target does not have complete mergeinfo, check
|
|
the log for the merge source.</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>Merging</title>
|
|
|
|
<para>Now, let us start merging!</para>
|
|
|
|
<sect5>
|
|
<title>The Principles</title>
|
|
|
|
<para>Say you would like to merge:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>revision <literal>$R</literal></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>in directory $target in stable branch
|
|
$B</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>from directory $source in head</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>$FSVN is
|
|
<literal>svn+ssh://svn.freebsd.org/base</literal></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Assuming that revisions $P and $Q have
|
|
already been merged, and that the current directory is
|
|
an up-to-date working copy of stable/$B, the
|
|
existing mergeinfo looks like this:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R $target</userinput>
|
|
$target - /head/$source:$P,$Q</screen>
|
|
|
|
<para>Merging is done like so:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn merge -c$R $FSVN/head/$source $target</userinput></screen>
|
|
|
|
<para>Checking the results of this is possible with
|
|
<command>svn diff</command>.</para>
|
|
|
|
<para>The svn:mergeinfo now looks like:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R $target</userinput>
|
|
$target - head/$source:$P,$Q,$R</screen>
|
|
|
|
<para>If the results are not exactly as shown, assistance
|
|
may be required before committing as mistakes may have
|
|
been made, or there may be something wrong with the
|
|
existing mergeinfo, or there may be a bug in
|
|
Subversion.</para>
|
|
</sect5>
|
|
|
|
<sect5>
|
|
<title>Practical Example</title>
|
|
|
|
<para>As a practical example, consider the following
|
|
scenario: The changes to <filename>netmap.4</filename>
|
|
in r238987 is to be merged from CURRENT to 9-STABLE.
|
|
The file resides in <filename>head/share/man/man4</filename> and
|
|
according to <xref linkend="svn-advanced-use-merging"/>
|
|
this is also where to do the merge. Note that in this
|
|
example all paths are relative to the top of the svn
|
|
repository. For more information on the directory
|
|
layout, see <xref linkend="svn-getting-started-base-layout"/>.</para>
|
|
|
|
<para>The first step is to inspect the existing
|
|
mergeinfo.</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R stable/9/share/man/man4</userinput></screen>
|
|
|
|
<para>Take a quick note of how it looks before moving on
|
|
to the next step; doing the actual merge:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn merge -c r238987 svn+ssh://svn.freebsd.org/base/head/share/man/man4 stable/9/share/man/man4</userinput>
|
|
--- Merging r238987 into 'stable/9/share/man/man4':
|
|
U stable/9/share/man/man4/netmap.4
|
|
--- Recording mergeinfo for merge of r238987 into
|
|
'stable/9/share/man/man4':
|
|
U stable/9/share/man/man4</screen>
|
|
|
|
<para>Check that the revision number of the merged
|
|
revision has been added. Once this is verified, the
|
|
only thing left is the actual commit.</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn commit stable/9/share/man/man4</userinput></screen>
|
|
</sect5>
|
|
|
|
<sect5>
|
|
<title>Merging into the Kernel
|
|
(<filename>sys/</filename>)</title>
|
|
|
|
<para>As stated above, merging into the kernel is
|
|
different from merging in the rest of the tree. In many
|
|
ways merging to the kernel is simpler because there is
|
|
always the same merge target
|
|
(<filename>sys/</filename>).</para>
|
|
|
|
<para>Once <command>svn merge</command> has been executed,
|
|
<command>svn diff</command> has to be run on the
|
|
directory to check the changes. This may show some
|
|
unrelated property changes, but these can be ignored.
|
|
Next, build and test the kernel, and, once the tests are
|
|
complete, commit the code as normal, making sure that
|
|
the commit message starts with <quote>Merge
|
|
<replaceable>r226222</replaceable> from head</quote>,
|
|
or similar.</para>
|
|
</sect5>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>Precautions Before Committing</title>
|
|
|
|
<para>As always, build world (or appropriate parts of
|
|
it).</para>
|
|
|
|
<para>Check the changes with <command>svn diff</command> and
|
|
<command>svn stat</command>. Make sure all the files that
|
|
should have been added or deleted were in fact added or
|
|
deleted.</para>
|
|
|
|
<para>Take a closer look at any property change (marked by a
|
|
<literal>M</literal> in the second column of <command>svn
|
|
stat</command>). Normally, no svn:mergeinfo properties
|
|
should be anywhere except the target directory (or
|
|
directories).</para>
|
|
|
|
<para>If something looks fishy, ask for help.</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>Committing</title>
|
|
|
|
<para>Make sure to commit a top level directory to have the
|
|
mergeinfo included as well. Do not specify individual
|
|
files on the command line. For more information about
|
|
committing files in general, see the relevant section of
|
|
this primer.</para>
|
|
</sect4>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-advanced-use-vendor-imports">
|
|
<title>Vendor Imports with <acronym>SVN</acronym></title>
|
|
|
|
<important>
|
|
<para>Please read this entire section before starting a
|
|
vendor import.</para>
|
|
</important>
|
|
|
|
<note>
|
|
<para>Patches to vendor code fall into two
|
|
categories:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Vendor patches: these are patches that have been
|
|
issued by the vendor, or that have been extracted from
|
|
the vendor's version control system, which address
|
|
issues which in your opinion cannot wait until the
|
|
next vendor release.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>&os; patches: these are patches that modify the
|
|
vendor code to address &os;-specific issues.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>The nature of a patch dictates where it should be
|
|
committed:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Vendor patches should be committed to the vendor
|
|
branch, and merged from there to head. If the patch
|
|
addresses an issue in a new release that is currently
|
|
being imported, it <emphasis>must not</emphasis> be
|
|
committed along with the new release: the release must
|
|
be imported and tagged first, then the patch can be
|
|
applied and committed. There is no need to re-tag the
|
|
vendor sources after committing the patch.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>&os; patches should be committed directly to
|
|
head.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</note>
|
|
|
|
<sect4>
|
|
<title>Preparing the Tree</title>
|
|
|
|
<para>If importing for the first time after the switch to
|
|
Subversion, flattening and cleaning up the vendor tree is
|
|
necessary, as well as bootstrapping the merge history in
|
|
the main tree.</para>
|
|
|
|
<sect5>
|
|
<title>Flattening</title>
|
|
|
|
<para>During the conversion from <acronym>CVS</acronym> to
|
|
Subversion, vendor branches were imported with the same
|
|
layout as the main tree. This means that the
|
|
<literal>pf</literal> vendor sources ended up in
|
|
<filename>vendor/pf/dist/contrib/pf</filename>. The
|
|
vendor source is best directly in
|
|
<filename>vendor/pf/dist</filename>.</para>
|
|
|
|
<para>To flatten the <literal>pf</literal> tree:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cd vendor/pf/dist/contrib/pf</userinput>
|
|
&prompt.user; <userinput>svn mv $(svn list) ../..</userinput>
|
|
&prompt.user; <userinput>cd ../..</userinput>
|
|
&prompt.user; <userinput>svn rm contrib</userinput>
|
|
&prompt.user; <userinput>svn propdel -R svn:mergeinfo .</userinput>
|
|
&prompt.user; <userinput>svn commit</userinput></screen>
|
|
|
|
<para>The <literal>propdel</literal> bit is necessary
|
|
because starting with 1.5, Subversion will automatically
|
|
add <literal>svn:mergeinfo</literal> to any directory
|
|
that is copied or moved. In this case, as nothing is
|
|
being merged from the deleted tree, they just get in the
|
|
way.</para>
|
|
|
|
<para>Tags may be flattened as well (3, 4, 3.5 etc.); the
|
|
procedure is exactly the same, only changing
|
|
<literal>dist</literal> to <literal>3.5</literal> or
|
|
similar, and putting the <command>svn commit</command>
|
|
off until the end of the process.</para>
|
|
</sect5>
|
|
|
|
<sect5>
|
|
<title>Cleaning Up</title>
|
|
|
|
<para>The <literal>dist</literal> tree can be cleaned up
|
|
as necessary. Disabling keyword expansion is
|
|
recommended, as it makes no sense on unmodified vendor
|
|
code and in some cases it can even be harmful.
|
|
<application>OpenSSH</application>, for example,
|
|
includes two files that originated with &os; and still
|
|
contain the original version tags. To do this:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn propdel svn:keywords -R .</userinput>
|
|
&prompt.user; <userinput>svn commit</userinput></screen>
|
|
</sect5>
|
|
|
|
<sect5>
|
|
<title>Bootstrapping Merge History</title>
|
|
|
|
<para>If importing for the first time after the switch to
|
|
Subversion, bootstrap <literal>svn:mergeinfo</literal>
|
|
on the target directory in the main tree to the revision
|
|
that corresponds to the last related change to the
|
|
vendor tree, prior to importing new sources:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cd head/contrib/pf</userinput>
|
|
&prompt.user; <userinput>svn merge --record-only svn+ssh://svn.freebsd.org/base/vendor/pf/dist@180876 .</userinput>
|
|
&prompt.user; <userinput>svn commit</userinput></screen>
|
|
</sect5>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>Importing New Sources</title>
|
|
|
|
<para>With two commits—one for the import itself and
|
|
one for the tag—this step can optionally be repeated
|
|
for every upstream release between the last import and the
|
|
current import.</para>
|
|
|
|
<sect5>
|
|
<title>Preparing the Vendor Sources</title>
|
|
|
|
<para>Unlike in <acronym>CVS</acronym> where only the
|
|
needed parts were imported into the vendor tree to avoid
|
|
bloating the main tree, Subversion is able to store a
|
|
full distribution in the vendor tree. So, import
|
|
everything, but merge only what is required.</para>
|
|
|
|
<para>A <command>svn add</command> is required to add any
|
|
files that were added since the last vendor import, and
|
|
<command>svn rm</command> is required to remove any that
|
|
were removed since. Preparing sorted lists of the
|
|
contents of the vendor tree and of the sources that are
|
|
about to be imported is recommended, to facilitate the
|
|
process.</para>
|
|
|
|
<screen>&prompt.user; <userinput>cd vendor/pf/dist</userinput>
|
|
&prompt.user; <userinput>svn list -R | grep -v '/$' | sort >../old</userinput>
|
|
&prompt.user; <userinput>cd ../pf-4.3</userinput>
|
|
&prompt.user; <userinput>find . -type f | cut -c 3- | sort >../new</userinput></screen>
|
|
|
|
<para>With these two files,
|
|
<command>comm -23 ../old ../new</command> will list
|
|
removed files (files only in <filename>old</filename>),
|
|
while <command>comm -13 ../old ../new</command> will
|
|
list added files only in
|
|
<filename>new</filename>.</para>
|
|
</sect5>
|
|
|
|
<sect5>
|
|
<title>Importing into the Vendor Tree</title>
|
|
|
|
<para>Now, the sources must be copied into
|
|
<filename>dist</filename> and
|
|
the <command>svn add</command> and
|
|
<command>svn rm</command> commands should be used as
|
|
needed:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cd vendor/pf/pf-4.3</userinput>
|
|
&prompt.user; <userinput>tar cf - . | tar xf - -C ../dist</userinput>
|
|
&prompt.user; <userinput>cd ../dist</userinput>
|
|
&prompt.user; <userinput>comm -23 ../old ../new | xargs svn rm</userinput>
|
|
&prompt.user; <userinput>comm -13 ../old ../new | xargs svn --parents add</userinput></screen>
|
|
|
|
<para>If any directories were removed, they will have to
|
|
be <command>svn rm</command>ed manually. Nothing will
|
|
break if they are not, but they will remain in the
|
|
tree.</para>
|
|
|
|
<para>Check properties on any new files. All text files
|
|
should have <literal>svn:eol-style</literal> set to
|
|
<literal>native</literal>. All binary files should have
|
|
<literal>svn:mime-type</literal> set to
|
|
<literal>application/octet-stream</literal> unless there
|
|
is a more appropriate media type. Executable files
|
|
should have <literal>svn:executable</literal> set to
|
|
<literal>*</literal>. No other properties should exist
|
|
on any file in the tree.</para>
|
|
|
|
<para>Committing is now possible, however it is good
|
|
practice to make sure that everything is OK by using the
|
|
<command>svn stat</command> and
|
|
<command>svn diff</command> commands.</para>
|
|
</sect5>
|
|
|
|
<sect5>
|
|
<title>Tagging</title>
|
|
|
|
<para>Once committed, vendor releases should be tagged for
|
|
future reference. The best and quickest way to do this
|
|
is directly in the repository:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn cp svn+ssh://svn.freebsd.org/base/vendor/pf/dist svn+ssh://svn.freebsd.org/base/vendor/pf/4.3</userinput></screen>
|
|
|
|
<para>Once that is complete, <command>svn up</command> the
|
|
working copy of
|
|
<filename>vendor/pf</filename>
|
|
to get the new tag, although this is rarely
|
|
needed.</para>
|
|
|
|
<para>If creating the tag in the working copy of the tree,
|
|
<command>svn:mergeinfo</command> results must be
|
|
removed:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cd vendor/pf</userinput>
|
|
&prompt.user; <userinput>svn cp dist 4.3</userinput>
|
|
&prompt.user; <userinput>svn propdel svn:mergeinfo -R 4.3</userinput></screen>
|
|
</sect5>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>Merging to Head</title>
|
|
|
|
<screen>&prompt.user; <userinput>cd head/contrib/pf</userinput>
|
|
&prompt.user; <userinput>svn up</userinput>
|
|
&prompt.user; <userinput>svn merge --accept=postpone svn+ssh://svn.freebsd.org/base/vendor/pf/dist .</userinput></screen>
|
|
|
|
<para>The <literal>--accept=postpone</literal> tells
|
|
Subversion that it should not complain because merge
|
|
conflicts will be taken care of manually.</para>
|
|
|
|
<para>It is necessary to resolve any merge conflicts.
|
|
This process is the same in <acronym>SVN</acronym> as in
|
|
<acronym>CVS</acronym>.</para>
|
|
|
|
<para>Make sure that any files that were added or removed in
|
|
the vendor tree have been properly added or removed in the
|
|
main tree. To check diffs against the vendor
|
|
branch:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=svn+ssh://svn.freebsd.org/base/vendor/pf/dist --new=.</userinput></screen>
|
|
|
|
<para>The <literal>--no-diff-deleted</literal> tells
|
|
Subversion not to complain about files that are in the
|
|
vendor tree but not in the main tree, i.e., things that
|
|
would have previously been removed before the vendor
|
|
import, like for example the vendor's makefiles
|
|
and configure scripts.</para>
|
|
|
|
<para>Using <acronym>CVS</acronym>, once a file was off the
|
|
vendor branch, it was not able to be put back. With
|
|
Subversion, there is no concept of on or off the vendor
|
|
branch. If a file that previously had local
|
|
modifications, to make it not show up in diffs in the
|
|
vendor tree, all that has to be done is remove any
|
|
left-over cruft like &os; version tags, which is much
|
|
easier.</para>
|
|
|
|
<para>If any changes are required for the world to build
|
|
with the new sources, make them now, and keep testing
|
|
until everything builds and runs perfectly.</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>Committing the Vendor Import</title>
|
|
|
|
<para>Committing is now possible! Everything must be
|
|
committed in one go. If done properly, the tree will move
|
|
from a consistent state with old code, to a consistent
|
|
state with new code.</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>From Scratch</title>
|
|
|
|
<sect5>
|
|
<title>Importing into the Vendor Tree</title>
|
|
|
|
<para>This section is an example of importing and tagging
|
|
<application>byacc</application> into
|
|
<filename>head</filename>.</para>
|
|
|
|
<para>First, prepare the directory in
|
|
<filename>vendor</filename>:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn co --depth immediates $FSVN/vendor</userinput>
|
|
&prompt.user; <userinput>cd vendor</userinput>
|
|
&prompt.user; <userinput>svn mkdir byacc</userinput>
|
|
&prompt.user; <userinput>svn mkdir byacc/dist</userinput></screen>
|
|
|
|
<para>Now, import the sources into the
|
|
<filename>dist</filename> directory.
|
|
Once the files are in place, <command>svn add</command>
|
|
the new ones, then <command>svn commit</command> and tag
|
|
the imported version. To save time and bandwidth,
|
|
direct remote committing and tagging is possible:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn cp -m "Tag byacc 20120115" $FSVN/vendor/byacc/dist $FSVN/vendor/byacc/20120115</userinput></screen>
|
|
</sect5>
|
|
|
|
<sect5>
|
|
<title>Merging to <literal>head</literal></title>
|
|
|
|
<para>Due to this being a new file, copy it for the
|
|
merge:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn cp -m "Import byacc to contrib" $FSVN/vendor/byacc/dist $FSVN/head/contrib/byacc</userinput></screen>
|
|
|
|
<para>Working normally on newly imported sources is still
|
|
possible.</para>
|
|
</sect5>
|
|
</sect4>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-advanced-use-reverting-a-commit">
|
|
<title>Reverting a Commit</title>
|
|
|
|
<para>Reverting a commit to a previous version is fairly
|
|
easy:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn merge -r179454:179453 ROADMAP.txt</userinput>
|
|
&prompt.user; <userinput>svn commit</userinput></screen>
|
|
|
|
<para>Change number syntax, with negative meaning a reverse
|
|
change, can also be used:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn merge -c -179454 ROADMAP.txt</userinput>
|
|
&prompt.user; <userinput>svn commit</userinput></screen>
|
|
|
|
<para>This can also be done directly in the repository:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn merge -r179454:179453 svn+ssh://svn.freebsd.org/base/ROADMAP.txt</userinput></screen>
|
|
|
|
<note>
|
|
<para>It is important to ensure that the mergeinfo
|
|
is correct when reverting a file in order to permit
|
|
<command>svn mergeinfo --eligible</command> to work as
|
|
expected.</para>
|
|
</note>
|
|
|
|
<para>Reverting the deletion of a file is slightly different.
|
|
Copying the version of the file that predates the deletion
|
|
is required. For example, to restore a file that was
|
|
deleted in revision N, restore version N-1:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn copy svn+ssh://svn.freebsd.org/base/ROADMAP.txt@179454</userinput>
|
|
&prompt.user; <userinput>svn commit</userinput></screen>
|
|
|
|
<para>or, equally:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn copy svn+ssh://svn.freebsd.org/base/ROADMAP.txt@179454 svn+ssh://svn.freebsd.org/base</userinput></screen>
|
|
|
|
<para>Do <emphasis>not</emphasis> simply recreate the file
|
|
manually and <command>svn add</command> it—this will
|
|
cause history to be lost.</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-advanced-use-fixing-mistakes">
|
|
<title>Fixing Mistakes</title>
|
|
|
|
<para>While we can do surgery in an emergency, do not plan on
|
|
having mistakes fixed behind the scenes. Plan on mistakes
|
|
remaining in the logs forever. Be sure to check the output
|
|
of <command>svn status</command> and <command>svn
|
|
diff</command> before committing.</para>
|
|
|
|
<para>Mistakes will happen but,
|
|
they can generally be fixed without
|
|
disruption.</para>
|
|
|
|
<para>Take a case of adding a file in the wrong location. The
|
|
right thing to do is to <command>svn move</command> the file
|
|
to the correct location and commit. This causes just a
|
|
couple of lines of metadata in the repository journal, and
|
|
the logs are all linked up correctly.</para>
|
|
|
|
<para>The wrong thing to do is to delete the file and then
|
|
<command>svn add</command> an independent copy in the
|
|
correct location. Instead of a couple of lines of text, the
|
|
repository journal grows an entire new copy of the file.
|
|
This is a waste.</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-advanced-use-setting-up-svnsync">
|
|
<title>Setting up a <application>svnsync</application>
|
|
Mirror</title>
|
|
|
|
<para>You probably do not want to do this unless there is a
|
|
good reason for it. Such reasons might be to support many
|
|
multiple local read-only client machines, or if your network
|
|
bandwidth is limited. Starting a fresh mirror from empty
|
|
would take a very long time. Expect a minimum of 10 hours
|
|
for high speed connectivity. If you have international
|
|
links, expect this to take 4 to 10 times longer.</para>
|
|
|
|
<para>A far better option is to grab a seed file. It is large
|
|
(~1GB) but will consume less network traffic and take less
|
|
time to fetch than a svnsync will. This is possible in one
|
|
of the following three ways:</para>
|
|
|
|
<screen>&prompt.user; <userinput>rsync -va --partial --progress freefall:/home/peter/svnmirror-base-r179637.tbz2 .</userinput></screen>
|
|
|
|
<screen>&prompt.user; <userinput>rsync -va --partial --progress rsync://repoman.freebsd.org:50873/svnseed/svnmirror-base-r215629.tar.xz .</userinput></screen>
|
|
|
|
<screen>&prompt.user; <userinput>fetch ftp://ftp.freebsd.org/pub/FreeBSD/development/subversion/svnmirror-base-r221445.tar.xz</userinput></screen>
|
|
|
|
<para>Once you have the file, extract it to somewhere like
|
|
<filename>home/svnmirror/base/</filename>.
|
|
Then, update it, so that it fetches changes since the last
|
|
revision in the archive:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svnsync sync file:///home/svnmirror/base</userinput></screen>
|
|
|
|
<para>You can then set that up to run from &man.cron.8;, do
|
|
checkouts locally, set up a svnserve server for your local
|
|
machines to talk to, etc.</para>
|
|
|
|
<para>The seed mirror is set to fetch from
|
|
<literal>svn://svn.freebsd.org/base</literal>. The
|
|
configuration for the mirror is stored in
|
|
<literal>revprop 0</literal> on the local mirror. To see
|
|
the configuration, try:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn proplist -v --revprop -r 0 file:///home/svnmirror/base</userinput></screen>
|
|
|
|
<para>Use <literal>propset</literal> to change things.</para>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-advanced-use-committing-high-ascii-data">
|
|
<title>Committing High-<acronym>ASCII</acronym> Data</title>
|
|
|
|
<para>Files that have high-<acronym>ASCII</acronym> bits are
|
|
considered binary files in <acronym>SVN</acronym>, so the
|
|
pre-commit checks fail and indicate that the
|
|
<literal>mime-type</literal> property should be set to
|
|
<literal>application/octet-stream</literal>. However, the
|
|
use of this is discouraged, so please do not set it. The
|
|
best way is always avoiding high-<acronym>ASCII</acronym>
|
|
data, so that it can be read everywhere with any text editor
|
|
but if it is not avoidable, instead of changing the
|
|
mime-type, set the <literal>fbsd:notbinary</literal>
|
|
property with <literal>propset</literal>:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn propset fbsd:notbinary yes foo.data</userinput></screen>
|
|
</sect3>
|
|
|
|
<sect3 xml:id="svn-advanced-use-maintaining-a-project-branch">
|
|
<title>Maintaining a Project Branch</title>
|
|
|
|
<para>A project branch is one that is synced to head (or
|
|
another branch) is used to develop a project then commit it
|
|
back to head. In <acronym>SVN</acronym>,
|
|
<quote>dolphin</quote> branching is used for this. A
|
|
<quote>dolphin</quote> branch is one that diverges for a
|
|
while and is finally committed back to the original branch.
|
|
During development code migration in one direction (from
|
|
head to the branch only). No code is committed back to head
|
|
until the end. Once you commit back at the end, the branch
|
|
is dead (although you can have a new branch with the same
|
|
name after you delete the branch if you want).</para>
|
|
|
|
<para>As per <link xlink:href="http://people.freebsd.org/~peter/svn_notes.txt">http://people.freebsd.org/~peter/svn_notes.txt</link>,
|
|
work that is intended to be merged back into HEAD should be
|
|
in <filename>base/projects/</filename>.
|
|
If you are doing work that is beneficial to the &os;
|
|
community in some way but not intended to be merged directly
|
|
back into HEAD then the proper location is <filename>base/user/your-name/</filename>.
|
|
<link xlink:href="http://svnweb.freebsd.org/base/projects/GUIDELINES.txt">This
|
|
page</link> contains further details.</para>
|
|
|
|
<para>To create a project branch:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn copy svn+ssh://svn.freebsd.org/base/head svn+ssh://svn.freebsd.org/base/projects/spif</userinput></screen>
|
|
|
|
<para>To merge changes from HEAD back into the project
|
|
branch:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cd copy_of_spif</userinput>
|
|
&prompt.user; <userinput>svn merge svn+ssh://svn.freebsd.org/base/head</userinput>
|
|
&prompt.user; <userinput>svn commit</userinput></screen>
|
|
|
|
<para>It is important to resolve any merge conflicts before
|
|
committing.</para>
|
|
<!--
|
|
<para>To collapse everything back at the end:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn write me</userinput></screen>
|
|
|
|
-->
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Some Tips</title>
|
|
|
|
<para>In commit logs etc., <quote>rev 179872</quote> should be
|
|
spelled <quote>r179872</quote> as per convention.</para>
|
|
|
|
<para>Do not remove and re-add the same file in a single commit
|
|
as this will break the CVS exporter.</para>
|
|
|
|
<para>Speeding up svn is possible by adding the following to
|
|
<filename>~/.ssh/config</filename>:</para>
|
|
|
|
<screen>Host *
|
|
ControlPath ~/.ssh/sockets/master-%l-%r@%h:%p
|
|
ControlMaster auto
|
|
ControlPersist yes</screen>
|
|
|
|
<para>and then typing</para>
|
|
|
|
<screen><userinput>mkdir ~/.ssh/sockets</userinput></screen>
|
|
|
|
<para>Checking out a working copy with a stock Subversion client
|
|
without &os;-specific patches
|
|
(<varname>OPTIONS_SET=FREEBSD_TEMPLATE</varname>) will mean
|
|
that <literal>$FreeBSD$</literal> tags will not
|
|
be expanded. Once the correct version has been installed,
|
|
trick Subversion into expanding them like so:</para>
|
|
|
|
<screen>&prompt.user; <userinput>svn propdel -R svn:keywords .</userinput>
|
|
&prompt.user; <userinput>svn revert -R .</userinput></screen>
|
|
|
|
<para>This will wipe out uncommitted patches.</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="conventions">
|
|
<title>Conventions and Traditions</title>
|
|
|
|
<para>As a new developer there are a number of things you should
|
|
do first. The first set is specific to committers only. (If
|
|
you are not a committer, e.g., have GNATS-only access, then your
|
|
mentor needs to do these things for you.)</para>
|
|
|
|
<sect2 xml:id="conventions-committers">
|
|
<title>Guidelines for Committers</title>
|
|
|
|
<note>
|
|
<para>The <literal>.ent</literal>, <literal>.xml</literal>,
|
|
and <literal>.xml</literal> files listed below exist in the
|
|
&os; Documentation Project SVN repository at
|
|
<systemitem class="fqdomainname">svn.FreeBSD.org/doc/</systemitem>.</para>
|
|
</note>
|
|
|
|
<para>If you have been given commit rights to one or more of the
|
|
repositories:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Add your author entity to
|
|
<filename>head/share/xml/authors.ent</filename>; this
|
|
should be done first since an omission of this commit will
|
|
cause the next commits to break the doc/ build.</para>
|
|
|
|
<para>This is a relatively easy task, but remains a good
|
|
first test of your version control skills.</para>
|
|
|
|
<important>
|
|
<para>New files that do not have the
|
|
<literal>FreeBSD=%H</literal>
|
|
<command>svn:keywords</command> property will be
|
|
rejected when attempting to commit them to the
|
|
repository. Be sure to read
|
|
<xref linkend="svn-daily-use-adding-and-removing"/>
|
|
regarding adding and removing files, in addition to
|
|
verifying that <filename>~/.subversion/config</filename>
|
|
contains the necessary "auto-props" entries
|
|
from <filename>auto-props.txt</filename> mentioned
|
|
there.</para>
|
|
</important>
|
|
|
|
<note>
|
|
<para>Do not forget to get mentor approval for these
|
|
patches!</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Add yourself to the <quote>Developers</quote> section
|
|
of the <link xlink:href="&url.articles.contributors;/index.html">Contributors
|
|
List</link>
|
|
(<filename>head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename>)
|
|
and remove yourself from the
|
|
<quote>Additional Contributors</quote> section
|
|
(<filename>head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename>).
|
|
Please note that entries are sorted by last name.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Add an entry for yourself to
|
|
<filename>head/share/xml/news.xml</filename>. Look for
|
|
the other entries that look like
|
|
<quote>A new committer</quote> and follow the
|
|
format.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You should add your PGP or GnuPG key to
|
|
<filename>head/share/pgpkeys</filename> (and if you do not
|
|
have a key, you should create one). Do not forget to
|
|
commit the updated
|
|
<filename>head/share/pgpkeys/pgpkeys.ent</filename> and
|
|
<filename>head/share/pgpkeys/pgpkeys-developers.xml</filename>.
|
|
Please note that entries are sorted by last name.</para>
|
|
|
|
<para>&a.des.email; has written a shell script
|
|
(<filename>head/share/pgpkeys/addkey.sh</filename>) to
|
|
make this extremely simple. See the <link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/pgpkeys/README">README</link>
|
|
file for more information.</para>
|
|
|
|
<note>
|
|
<para>It is important to have an up-to-date PGP/GnuPG key
|
|
in the Handbook, since the key may be required for
|
|
positive identification of a committer, e.g., by the
|
|
&a.admins; for account recovery. A complete keyring of
|
|
<systemitem class="fqdomainname">FreeBSD.org</systemitem> users is
|
|
available for download from <link xlink:href="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</link>.</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Add an entry for yourself to
|
|
<filename>src/share/misc/committers-repository.dot</filename>,
|
|
where repository is either doc, ports or src, depending on
|
|
the commit privileges you obtained.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Some people add an entry for themselves to
|
|
<filename>ports/astro/xearth/files/freebsd.committers.markers</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Some people add an entry for themselves to
|
|
<filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you already have an account at the
|
|
<link xlink:href="http://wiki.freebsd.org">&os; wiki</link>,
|
|
make sure your mentor moves you from the <link xlink:href="http://wiki.freebsd.org/ContributorsGroup">Contributors
|
|
group</link> to the <link xlink:href="http://wiki.freebsd.org/DevelopersGroup">Developers
|
|
group</link>. Otherwise, consider signing up for an
|
|
account so you can publish projects and ideas you are
|
|
working on.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Once you get access to the wiki, you may add yourself
|
|
to the
|
|
<link xlink:href="http://wiki.freebsd.org/HowWeGotHere">How We
|
|
Got Here</link> and
|
|
<link xlink:href="http://wiki.freebsd.org/IrcNicks">Irc
|
|
Nicks</link> pages.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you subscribe to &a.svn-src-all.name;,
|
|
&a.svn-ports-all.name; or &a.svn-doc-all.name;, you will
|
|
probably want to unsubscribe to avoid receiving duplicate
|
|
copies of commit messages and their followups.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<note>
|
|
<para>All <filename>src</filename> commits should go to
|
|
&os.current; first before being merged to &os.stable;. No
|
|
major new features or high-risk modifications should be made
|
|
to the &os.stable; branch.</para>
|
|
</note>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="conventions-everyone">
|
|
<title>Guidelines for Everyone</title>
|
|
|
|
<para>Whether or not you have commit rights:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Introduce yourself to the other developers, otherwise
|
|
no one will have any idea who you are or what you are
|
|
working on. You do not have to write a comprehensive
|
|
biography, just write a paragraph or two about who you are
|
|
and what you plan to be working on as a developer in
|
|
&os;. (You should also mention who your mentor will
|
|
be). Email this to the &a.developers; and you will be on
|
|
your way!</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Log into <systemitem>hub.FreeBSD.org</systemitem> and create a
|
|
<filename>/var/forward/user</filename>
|
|
(where <replaceable>user</replaceable> is your username)
|
|
file containing the e-mail address where you want mail
|
|
addressed to
|
|
<replaceable>yourusername</replaceable>@FreeBSD.org to be
|
|
forwarded. This includes all of the commit messages as
|
|
well as any other mail addressed to the &a.committers; and
|
|
the &a.developers;. Really large mailboxes which have
|
|
taken up permanent residence on <systemitem>hub</systemitem> often
|
|
get <quote>accidentally</quote> truncated without warning,
|
|
so forward it or read it and you will not lose it.</para>
|
|
|
|
<para>Due to the severe load dealing with SPAM places on the
|
|
central mail servers that do the mailing list processing
|
|
the front-end server does do some basic checks and will
|
|
drop some messages based on these checks. At the moment
|
|
proper DNS information for the connecting host is the only
|
|
check in place but that may change. Some people blame
|
|
these checks for bouncing valid email. If you want these
|
|
checks turned off for your email you can place a file
|
|
named <filename>.spam_lover</filename> in your home
|
|
directory on
|
|
<systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> to
|
|
disable the checks for your email.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<note>
|
|
<para>If you are a developer but not a committer, you will
|
|
not be subscribed to the committers or developers mailing
|
|
lists; the subscriptions are derived from the access
|
|
rights.</para>
|
|
</note>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="mentors">
|
|
<title>Mentors</title>
|
|
|
|
<para>All new developers also have a mentor assigned to them for
|
|
the first few months. Your mentor is responsible for teaching
|
|
you the rules and conventions of the project and guiding your
|
|
first steps in the developer community. Your mentor is also
|
|
personally responsible for your actions during this initial
|
|
period.</para>
|
|
|
|
<para>For committers: until your mentor decides (and announces
|
|
with a commit to <filename>mentors</filename>) that you
|
|
have learned the ropes and are ready to commit on your own,
|
|
you should not commit anything without first getting your
|
|
mentor's review and approval, and you should document that
|
|
approval with an <literal>Approved by:</literal> line in the
|
|
commit message.</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="commit-log-message">
|
|
<title>Commit Log Messages</title>
|
|
|
|
<para>This section contains some suggestions and traditions for
|
|
how commit logs are formatted.</para>
|
|
|
|
<para>As well as including an informative message with each
|
|
commit you may need to include some additional
|
|
information.</para>
|
|
|
|
<para>This information consists of one or more lines
|
|
containing the key word or phrase, a colon, tabs for
|
|
formatting, and then the additional information.</para>
|
|
|
|
<para>The key words or phrases are:</para>
|
|
|
|
<informaltable frame="none" pgwide="1">
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>PR:</literal></entry>
|
|
<entry>The problem report (if any) which is affected
|
|
(typically, by being closed) by this
|
|
commit. Only include one PR per line as the
|
|
automated scripts which parse this line can not
|
|
understand more than one.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>Submitted by:</literal></entry>
|
|
<entry><para>The name and e-mail address of the person
|
|
that submitted the fix; for developers, just the
|
|
username on the &os; cluster.</para>
|
|
<para>If the submitter is the maintainer of the port
|
|
to which you are commiting include "(maintainer)"
|
|
after the email address.</para>
|
|
<para>Avoid obfuscating the
|
|
email address of the submitter as this adds
|
|
additional work when searching logs.</para>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>Reviewed by:</literal></entry>
|
|
<entry>The name and e-mail address of the person or
|
|
people that reviewed the change; for developers,
|
|
just the username on the &os; cluster. If a
|
|
patch was submitted to a mailing list for review,
|
|
and the review was favorable, then just include
|
|
the list name.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>Approved by:</literal></entry>
|
|
<entry><para>The name and e-mail address of the person or
|
|
people that approved the change; for developers,
|
|
just the username on the &os; cluster. It is
|
|
customary to get prior approval for a commit if it
|
|
is to an area of the tree to which you do not
|
|
usually commit. In addition, during the run up to
|
|
a new release all commits
|
|
<emphasis>must</emphasis> be approved by the
|
|
release engineering team.</para>
|
|
|
|
<para>If these are your first
|
|
commits then you should have passed them past your
|
|
mentor first, and you should list your mentor, as
|
|
in ``<replaceable>username-of-mentor</replaceable>
|
|
<literal>(mentor)</literal>''.</para>
|
|
|
|
<para>If a team approved these commits
|
|
then include the team
|
|
name followed by the username of the approver in
|
|
parentheses. For example: ``<replaceable>re@
|
|
(username)</replaceable>``</para></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>Obtained from:</literal></entry>
|
|
<entry>The name of the project (if any) from which
|
|
the code was obtained. Do not use this line for the
|
|
name of an individual person.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>MFC after:</literal></entry>
|
|
<entry>If you wish to receive an e-mail reminder to
|
|
<acronym>MFC</acronym> at a later date, specify
|
|
the number of days, weeks, or months after which
|
|
an <acronym>MFC</acronym> is planned.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>Security:</literal></entry>
|
|
<entry>If the change is related to a security
|
|
vulnerability or security exposure, include one or
|
|
more references or a description of the
|
|
issue. If possible, include a VuXML URL or a CVE ID.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<example>
|
|
<title>Commit Log for a Commit Based on a PR</title>
|
|
|
|
<para>You want to commit a change based on a PR submitted
|
|
by John Smith containing a patch. The end of the commit
|
|
message should look something like this.</para>
|
|
|
|
<programlisting>...
|
|
|
|
PR: foo/12345
|
|
Submitted by: John Smith <John.Smith@example.com></programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Commit Log for a Commit Needing Review</title>
|
|
|
|
<para>You want to change the virtual memory system. You
|
|
have posted patches to the appropriate mailing list (in
|
|
this case, <literal>freebsd-arch</literal>) and the
|
|
changes have been approved.</para>
|
|
|
|
<programlisting>...
|
|
|
|
Reviewed by: -arch</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Commit Log for a Commit Needing Approval</title>
|
|
|
|
<para>You want to commit a port
|
|
You have collaborated with
|
|
the listed MAINTAINER, who has told you to go ahead and
|
|
commit.</para>
|
|
|
|
<programlisting>...
|
|
|
|
Approved by: <replaceable>abc</replaceable> (maintainer)</programlisting>
|
|
|
|
<para>Where <replaceable>abc</replaceable> is the account
|
|
name of the person who approved.</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Commit Log for a Commit Bringing in Code from
|
|
OpenBSD</title>
|
|
|
|
<para>You want to commit some code based on work done in
|
|
the OpenBSD project.</para>
|
|
|
|
<programlisting>...
|
|
|
|
Obtained from: OpenBSD</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Commit Log for a Change to &os.current; with a
|
|
Planned Commit to &os.stable; to Follow at a Later
|
|
Date.</title>
|
|
|
|
<para>You want to commit some code which will be merged
|
|
from &os.current; into the &os.stable; branch after two
|
|
weeks.</para>
|
|
|
|
<programlisting>...
|
|
|
|
MFC after: <replaceable>2 weeks</replaceable></programlisting>
|
|
|
|
<para>Where <replaceable>2</replaceable> is the number of
|
|
days, weeks, or months after which an
|
|
<acronym>MFC</acronym> is planned. The
|
|
<replaceable>weeks</replaceable> option may be
|
|
<literal>day</literal>, <literal>days</literal>,
|
|
<literal>week</literal>, <literal>weeks</literal>,
|
|
<literal>month</literal>,
|
|
<literal>months</literal>.</para>
|
|
</example>
|
|
|
|
<para>In many cases you may need to combine some of
|
|
these.</para>
|
|
|
|
<para>Consider the situation where a user has submitted a PR
|
|
containing code from the NetBSD project. You are looking
|
|
at the PR, but it is not an area of the tree you normally
|
|
work in, so you have decided to get the change reviewed by
|
|
the <literal>arch</literal> mailing list. Since the
|
|
change is complex, you opt to <acronym>MFC</acronym> after
|
|
one month to allow adequate testing.</para>
|
|
|
|
<para>The extra information to include in the commit would
|
|
look something like</para>
|
|
<example>
|
|
<title>Example Combined Commit Log</title>
|
|
<programlisting>PR: foo/54321
|
|
Submitted by: John Smith <John.Smith@example.com>
|
|
Reviewed by: -arch
|
|
Obtained from: NetBSD
|
|
MFC after: 1 month</programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="pref-license">
|
|
<title>Preferred License for New Files</title>
|
|
|
|
<para>Currently the &os; Project suggests and uses the following
|
|
text as the preferred license scheme:</para>
|
|
|
|
<programlisting>/*-
|
|
* Copyright (c) [year] [your name]
|
|
* All rights reserved.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions
|
|
* are met:
|
|
* 1. Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in the
|
|
* documentation and/or other materials provided with the distribution.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
* SUCH DAMAGE.
|
|
*
|
|
* [id for your version control system, if any]
|
|
*/</programlisting>
|
|
|
|
<para>The &os; project strongly discourages the so-called
|
|
"advertising clause" in new code. Due to the large number of
|
|
contributors to the &os; project, complying with this clause for
|
|
many commercial vendors has become difficult. If you have code
|
|
in the tree with the advertising clause, please consider
|
|
removing it. In fact, please consider using the above license
|
|
for your code.</para>
|
|
|
|
<para>The &os; project discourages completely new licenses and
|
|
variations on the standard licenses. New licenses require the
|
|
approval of the &a.core; to reside in the
|
|
main repository. The more different licenses that are used in
|
|
the tree, the more problems that this causes to those wishing to
|
|
utilize this code, typically from unintended consequences from a
|
|
poorly worded license.</para>
|
|
|
|
<para>Project policy dictates that code under some non-BSD
|
|
licenses must be placed only in specific sections of the
|
|
repository, and in some cases, compilation must be conditional
|
|
or even disabled by default. For example, the GENERIC kernel
|
|
must be compiled under only licenses identical to or
|
|
substantially similar to the BSD license. GPL, APSL, CDDL, etc,
|
|
licensed software must not be compiled into GENERIC.</para>
|
|
|
|
<para>Developers are reminded that in open source, getting "open"
|
|
right is just as important as getting "source" right, as
|
|
improper handling of intellectual property has serious
|
|
consequences. Any questions or concerns should immediately be
|
|
brought to the attention of the core team.</para>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="developer.relations">
|
|
<title>Developer Relations</title>
|
|
|
|
<para>If you are working directly on your own code or on code
|
|
which is already well established as your responsibility, then
|
|
there is probably little need to check with other committers
|
|
before jumping in with a commit. If you see a bug in an area of
|
|
the system which is clearly orphaned (and there are a few such
|
|
areas, to our shame), the same applies. If, however, you are
|
|
about to modify something which is clearly being actively
|
|
maintained by someone else (and it is only by watching the
|
|
<literal>repository-committers</literal>
|
|
mailing list that you can really get a feel for just what is and
|
|
is not) then consider sending the change to them instead, just
|
|
as you would have before becoming a committer. For ports, you
|
|
should contact the listed <varname>MAINTAINER</varname> in the
|
|
<filename>Makefile</filename>. For other parts of the
|
|
repository, if you are unsure who the active maintainer might
|
|
be, it may help to scan the revision history to see who has
|
|
committed changes in the past. &a.fenner.email; has written a nice
|
|
shell script that can help determine who the active maintainer
|
|
might be. It lists each person who has committed to a given
|
|
file along with the number of commits each person has made. It
|
|
can be found on <systemitem>freefall</systemitem> at
|
|
<filename>~fenner/bin/whodid</filename>. If your queries go
|
|
unanswered or the committer otherwise indicates a lack of
|
|
interest in the area affected, go ahead and commit it.</para>
|
|
|
|
<para>If you are unsure about a commit for any reason at
|
|
all, have it reviewed by <literal>-hackers</literal>
|
|
before committing. Better to have it flamed then and there
|
|
rather than when it is part of the repository. If you do
|
|
happen to commit something which results in controversy
|
|
erupting, you may also wish to consider backing the change out
|
|
again until the matter is settled. Remember – with a
|
|
version control system we can always change it back.</para>
|
|
|
|
<para>Do not impugn the intentions of someone you disagree with.
|
|
If they see a different solution to a problem than you, or even
|
|
a different problem, it is not because they are stupid, because
|
|
they have questionable parentage, or because they are trying to
|
|
destroy your hard work, personal image, or &os;, but simply
|
|
because they have a different outlook on the world. Different
|
|
is good.</para>
|
|
|
|
<para>Disagree honestly. Argue your position from its merits,
|
|
be honest about any shortcomings it may have, and be open to
|
|
seeing their solution, or even their vision of the problem,
|
|
with an open mind.</para>
|
|
|
|
<para>Accept correction. We are all fallible. When you have made
|
|
a mistake, apologize and get on with life. Do not beat up
|
|
yourself, and certainly do not beat up others for your mistake.
|
|
Do not waste time on embarrassment or recrimination, just fix
|
|
the problem and move on.</para>
|
|
|
|
<para>Ask for help. Seek out (and give) peer reviews. One of
|
|
the ways open source software is supposed to excel is in the
|
|
number of eyeballs applied to it; this does not apply if nobody
|
|
will review code.</para>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="if-in-doubt">
|
|
<title>If in doubt...</title>
|
|
|
|
<para>When you are not sure about something, whether it be a
|
|
technical issue or a project convention be sure to ask. If you
|
|
stay silent you will never make progress.</para>
|
|
|
|
<para>If it relates to a technical issue ask on the public
|
|
mailing lists. Avoid the temptation to email the individual
|
|
person that knows the answer. This way everyone will be able to
|
|
learn from the question and the answer.</para>
|
|
|
|
<para>For project specific or administrative questions you should
|
|
ask, in order: </para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Your mentor or former mentor.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>An experienced committer on IRC, email, etc.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Any team with a "hat", as they should give you a
|
|
definitive answer.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If still not sure, ask on &a.developers;.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Once your question is answered, if no one pointed you to
|
|
documentation that spelled out the answer to your question,
|
|
document it, as others will have the same question.</para>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="gnats">
|
|
<title>GNATS</title>
|
|
|
|
<para>The &os; Project utilizes
|
|
<application>GNATS</application> for tracking bugs and change
|
|
requests. Be sure that if you commit a fix or suggestion found
|
|
in a <application>GNATS</application> PR, you use
|
|
<command>edit-pr pr-number</command>
|
|
on <systemitem>freefall</systemitem> to close it. It is also considered
|
|
nice if you take time to close any PRs associated with your
|
|
commits, if appropriate. You can also make use of
|
|
&man.send-pr.1; yourself for proposing any change which you feel
|
|
should probably be made, pending a more extensive peer-review
|
|
first.</para>
|
|
|
|
<para>You can find out more about <application>GNATS</application>
|
|
at:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><link xlink:href="&url.articles.pr-guidelines;/index.html">&os;
|
|
Problem Report Handling Guidelines</link></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><uri xlink:href="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html">http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html</uri></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><link xlink:href="&url.base;/support.html">http://www.FreeBSD.org/support.html</link></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>&man.send-pr.1;</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>You can run a local copy of GNATS, and then integrate the
|
|
&os; GNATS tree by creating an
|
|
<application>rsync</application> mirror. Then you can run GNATS
|
|
commands locally, allowing you to query the PR database without
|
|
an Internet connection.</para>
|
|
|
|
<sect2>
|
|
<title>Mirroring the GNATS Tree</title>
|
|
|
|
<para>It is possible to mirror the GNATS database by installing
|
|
<package>net/rsync</package>, and
|
|
executing:</para>
|
|
|
|
<screen>&prompt.user; <userinput>rsync -va rsync://bit0.us-west.freebsd.org/FreeBSD-bit/gnats .</userinput></screen>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="gnatstools">
|
|
<title>Useful Tools</title>
|
|
|
|
<para>Other than <command>edit-pr</command> there are a
|
|
collection of tools in <filename>~gnats/tools/</filename>
|
|
on <systemitem>freefall</systemitem> which can make working with PRs
|
|
much easier.</para>
|
|
|
|
<para><command>open-pr</command>, <command>close-pr</command>,
|
|
<command>take-pr</command>, and <command>feedback-pr</command>
|
|
take PR numbers as arguments and then ask you to select from a
|
|
preexisting list of change reasons or let you type in your
|
|
own.</para>
|
|
|
|
<para><command>change-pr</command> is a multi purpose tool
|
|
that lets you make multiple changes at the same time with one
|
|
command.</para>
|
|
|
|
<para>For example, to assign PR 123456 to yourself type
|
|
<command>take-pr 123456</command>.
|
|
If you want to set the PR to patched awaiting an MFC at
|
|
the same time use:
|
|
<command>change-pr -t -p -m "awaiting MFC"
|
|
123456</command></para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="people">
|
|
<title>Who's Who</title>
|
|
|
|
<para>Besides the repository meisters, there are other &os;
|
|
project members and teams whom you will probably get to know in
|
|
your role as a committer. Briefly, and by no means
|
|
all-inclusively, these are:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>&a.doceng;</term>
|
|
|
|
<listitem>
|
|
<para>doceng is the group responsible for the documentation
|
|
build infrastructure, approving new documentation
|
|
committers, and ensuring that the &os; website and
|
|
documentation on the FTP site is up to date with respect
|
|
to the CVS tree. It is not a conflict resolution body.
|
|
The vast majority of documentation related discussion
|
|
takes place on the &a.doc;. More details regarding the
|
|
doceng team can be found in its <link xlink:href="http://www.FreeBSD.org/internal/doceng.html">charter</link>.
|
|
Committers interested in contributing to the documentation
|
|
should familiarize themselves with the <link xlink:href="&url.books.fdp-primer;/index.html">Documentation
|
|
Project Primer</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.ru.email;</term>
|
|
|
|
<listitem>
|
|
<para>Ruslan is Mister &man.mdoc.7;. If you are writing a
|
|
manual page and need some advice on the structure, or the
|
|
markup, ask Ruslan.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.bde.email;</term>
|
|
|
|
<listitem>
|
|
<para>Bruce is the Style Police-Meister. When you do a
|
|
commit that could have been done better, Bruce will be
|
|
there to tell you. Be thankful that someone is. Bruce is
|
|
also very knowledgeable on the various standards
|
|
applicable to &os;.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.re.members.email;</term>
|
|
|
|
<listitem>
|
|
<para>These are the members of the &a.re;. This team is
|
|
responsible for setting release deadlines and controlling
|
|
the release process. During code freezes, the release
|
|
engineers have final authority on all changes to the
|
|
system for whichever branch is pending release status. If
|
|
there is something you want merged from &os.current; to
|
|
&os.stable; (whatever values those may have at any given
|
|
time), these are the people to talk to about it.</para>
|
|
|
|
<para>Hiroki is also the keeper of the release documentation
|
|
(<filename>src/release/doc/*</filename>). If you commit a
|
|
change that you think is worthy of mention in the release
|
|
notes, please make sure he knows about it. Better still,
|
|
send him a patch with your suggested commentary.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.des.email;</term>
|
|
|
|
<listitem>
|
|
<para>Dag-Erling is the
|
|
<link xlink:href="&url.base;/security/">&os; Security
|
|
Officer</link> and oversees the
|
|
&a.security-officer;.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.wollman.email;</term>
|
|
|
|
<listitem>
|
|
<para>If you need advice on obscure network internals or
|
|
are not sure of some potential change to the networking
|
|
subsystem you have in mind, Garrett is someone to talk
|
|
to. Garrett is also very knowledgeable on the various
|
|
standards applicable to &os;.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.committers;</term>
|
|
|
|
<listitem>
|
|
<para>&a.svn-src-all.name;, &a.svn-ports-all.name; and
|
|
&a.svn-doc-all.name; are the mailing lists that the
|
|
version control system uses to send commit messages to.
|
|
You should <emphasis>never</emphasis> send email directly
|
|
to these lists. You should only send replies to this list
|
|
when they are short and are directly related to a
|
|
commit.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.developers;</term>
|
|
|
|
<listitem>
|
|
<para>All committers are subscribed to -developers. This
|
|
list was created to be a forum for the committers
|
|
<quote>community</quote> issues. Examples are Core
|
|
voting, announcements, etc.</para>
|
|
|
|
<para>The &a.developers; is for the exclusive use of &os;
|
|
committers. In order to develop &os;, committers must
|
|
have the ability to openly discuss matters that will be
|
|
resolved before they are publicly announced. Frank
|
|
discussions of work in progress are not suitable for open
|
|
publication and may harm &os;.</para>
|
|
|
|
<para>All &os; committers are reminded to obey the
|
|
copyright of the original author(s) of &a.developers;
|
|
mail. Do not publish or forward messages from the
|
|
&a.developers; outside the list membership without
|
|
permission of all of the authors.</para>
|
|
|
|
<para>Copyright violators will be removed from the
|
|
&a.developers;, resulting in a suspension of commit
|
|
privileges. Repeated or flagrant violations may result in
|
|
permanent revocation of commit privileges.</para>
|
|
|
|
<para>This list is <emphasis>not</emphasis> intended as a
|
|
place for code reviews or a replacement for the &a.arch;.
|
|
In fact using it as such hurts the &os; Project as it
|
|
gives a sense of a closed list where general decisions
|
|
affecting all of the &os; using community are made
|
|
without being <quote>open</quote>. Last, but not least
|
|
<emphasis>never, never ever, email the &a.developers; and
|
|
CC:/BCC: another &os; list</emphasis>. Never, ever
|
|
email another &os; email list and CC:/BCC: the
|
|
&a.developers;. Doing so can greatly diminish the
|
|
benefits of this list.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="ssh.guide">
|
|
<title>SSH Quick-Start Guide</title>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>If you do not wish to type your password in every
|
|
time you use &man.ssh.1;, and you use RSA or DSA keys to
|
|
authenticate, &man.ssh-agent.1; is there for your
|
|
convenience. If you want to use &man.ssh-agent.1;, make
|
|
sure that you run it before running other applications. X
|
|
users, for example, usually do this from their
|
|
<filename>.xsession</filename> or
|
|
<filename>.xinitrc</filename>. See &man.ssh-agent.1;
|
|
for details.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Generate a key pair using &man.ssh-keygen.1;. The key
|
|
pair will wind up in your
|
|
<filename>$HOME/.ssh/</filename>
|
|
directory.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Send your public key
|
|
(<filename>$HOME/.ssh/id_dsa.pub</filename>
|
|
or
|
|
<filename>$HOME/.ssh/id_rsa.pub</filename>)
|
|
to the person setting you up as a committer so it can be put
|
|
into the
|
|
<filename>yourlogin</filename>
|
|
file in
|
|
<filename>/etc/ssh-keys/</filename> on
|
|
<systemitem>freefall</systemitem>.</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<para>Now you should be able to use &man.ssh-add.1; for
|
|
authentication once per session. This will prompt you for
|
|
your private key's pass phrase, and then store it in your
|
|
authentication agent (&man.ssh-agent.1;). If you no longer
|
|
wish to have your key stored in the agent, issuing
|
|
<command>ssh-add -d</command> will remove it.</para>
|
|
|
|
<para>Test by doing something such as <command>ssh
|
|
freefall.FreeBSD.org ls /usr</command>.</para>
|
|
|
|
<para>For more information, see
|
|
<package>security/openssh</package>,
|
|
&man.ssh.1;, &man.ssh-add.1;, &man.ssh-agent.1;,
|
|
&man.ssh-keygen.1;, and &man.scp.1;.</para>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="coverity">
|
|
<title>&coverity; Availability for &os; Committers</title>
|
|
|
|
<para>All &os; developers can obtain access to
|
|
<application>Coverity</application> analysis results of
|
|
all &os; Project software. All who are interested
|
|
in obtaining access to
|
|
the analysis results of the automated
|
|
<application>Coverity</application> runs, can
|
|
sign up at <uri
|
|
xlink:href="http://scan.coverity.com/">Coverity Scan</uri></para>
|
|
|
|
<para>The &os; wiki includes a mini-guide for developers who are
|
|
interested in working with the &coverity; analysis
|
|
reports:
|
|
<uri xlink:href="http://wiki.freebsd.org/CoverityPrevent">http://wiki.freebsd.org/CoverityPrevent</uri>.
|
|
Please note that this mini-guide is only readable by &os;
|
|
developers, so if you cannot access this page, you will have to
|
|
ask someone to add you to the appropriate Wiki access
|
|
list.</para>
|
|
|
|
<para>Finally, all &os; developers who are going to use
|
|
&coverity; are always encouraged to ask for more details
|
|
and usage information, by posting any questions to the mailing
|
|
list of the &os; developers.</para>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="rules">
|
|
<title>The &os; Committers' Big List of Rules</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Respect other committers.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect other contributors.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Discuss any significant change
|
|
<emphasis>before</emphasis> committing.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect existing maintainers (if listed in the
|
|
<varname>MAINTAINER</varname> field in
|
|
<filename>Makefile</filename> or in the
|
|
<filename>MAINTAINER</filename> file in the top-level
|
|
directory).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Any disputed change must be backed out pending
|
|
resolution of the dispute if requested by a maintainer.
|
|
Security related changes may
|
|
override a maintainer's wishes at the Security Officer's
|
|
discretion.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes go to &os.current; before
|
|
&os.stable; unless specifically permitted by
|
|
the release engineer or unless they are not applicable to
|
|
&os.current;. Any non-trivial or non-urgent
|
|
change which is applicable should also be allowed to sit in
|
|
&os.current; for at least 3 days before
|
|
merging so that it can be given sufficient testing. The
|
|
release engineer has the same authority over the
|
|
&os.stable; branch as outlined for the
|
|
maintainer in rule #5.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Do not fight in public with other committers; it looks
|
|
bad. If you must <quote>strongly disagree</quote> about
|
|
something, do so only in private.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect all code freezes and read the
|
|
<literal>committers</literal> and
|
|
<literal>developers</literal> mailing lists in a timely
|
|
manner so you know when a code freeze is in effect.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When in doubt on any procedure, ask first!</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Test your changes before committing them.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Do not commit to anything under the
|
|
<filename>src/contrib</filename>,
|
|
<filename>src/crypto</filename>, or
|
|
<filename>src/sys/contrib</filename> trees without
|
|
<emphasis>explicit</emphasis> approval from the respective
|
|
maintainer(s).</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>As noted, breaking some of these rules can be grounds for
|
|
suspension or, upon repeated offense, permanent removal of
|
|
commit privileges. Individual members of core have the power to
|
|
temporarily suspend commit privileges until core as a whole has
|
|
the chance to review the issue. In case of an
|
|
<quote>emergency</quote> (a committer doing damage to the
|
|
repository), a temporary suspension may also be done by the
|
|
repository meisters. Only a 2/3 majority of core has the
|
|
authority to suspend commit privileges for longer than a week or
|
|
to remove them permanently. This rule does not exist to set
|
|
core up as a bunch of cruel dictators who can dispose of
|
|
committers as casually as empty soda cans, but to give the
|
|
project a kind of safety fuse. If someone is out of control, it
|
|
is important to be able to deal with this immediately rather
|
|
than be paralyzed by debate. In all cases, a committer whose
|
|
privileges are suspended or revoked is entitled to a
|
|
<quote>hearing</quote> by core, the total duration of the
|
|
suspension being determined at that time. A committer whose
|
|
privileges are suspended may also request a review of the
|
|
decision after 30 days and every 30 days thereafter (unless the
|
|
total suspension period is less than 30 days). A committer
|
|
whose privileges have been revoked entirely may request a review
|
|
after a period of 6 months has elapsed. This review policy is
|
|
<emphasis>strictly informal</emphasis> and, in all cases, core
|
|
reserves the right to either act on or disregard requests for
|
|
review if they feel their original decision to be the right
|
|
one.</para>
|
|
|
|
<para>In all other aspects of project operation, core is a subset
|
|
of committers and is bound by the
|
|
<emphasis>same rules</emphasis>. Just because someone is in
|
|
core this does not mean that they have special dispensation to
|
|
step outside any of the lines painted here; core's
|
|
<quote>special powers</quote> only kick in when it acts as a
|
|
group, not on an individual basis. As individuals, the core
|
|
team members are all committers first and core second.</para>
|
|
|
|
<sect2>
|
|
<title>Details</title>
|
|
|
|
<orderedlist>
|
|
<listitem xml:id="respect">
|
|
<para>Respect other committers.</para>
|
|
|
|
<para>This means that you need to treat other committers as
|
|
the peer-group developers that they are. Despite our
|
|
occasional attempts to prove the contrary, one does not
|
|
get to be a committer by being stupid and nothing rankles
|
|
more than being treated that way by one of your peers.
|
|
Whether we always feel respect for one another or not (and
|
|
everyone has off days), we still have to
|
|
<emphasis>treat</emphasis> other committers with respect
|
|
at all times, on public forums and in private
|
|
email.</para>
|
|
|
|
<para>Being able to work together long term is this
|
|
project's greatest asset, one far more important than any
|
|
set of changes to the code, and turning arguments about
|
|
code into issues that affect our long-term ability to work
|
|
harmoniously together is just not worth the trade-off by
|
|
any conceivable stretch of the imagination.</para>
|
|
|
|
<para>To comply with this rule, do not send email when you
|
|
are angry or otherwise behave in a manner which is likely
|
|
to strike others as needlessly confrontational. First
|
|
calm down, then think about how to communicate in the most
|
|
effective fashion for convincing the other person(s) that
|
|
your side of the argument is correct, do not just blow off
|
|
some steam so you can feel better in the short term at the
|
|
cost of a long-term flame war. Not only is this very bad
|
|
<quote>energy economics</quote>, but repeated displays of
|
|
public aggression which impair our ability to work well
|
|
together will be dealt with severely by the project
|
|
leadership and may result in suspension or termination of
|
|
your commit privileges. The project leadership will take
|
|
into account both public and private communications
|
|
brought before it. It will not seek the disclosure of
|
|
private communications, but it will take it into account
|
|
if it is volunteered by the committers involved in the
|
|
complaint.</para>
|
|
|
|
<para>All of this is never an option which the project's
|
|
leadership enjoys in the slightest, but unity comes first.
|
|
No amount of code or good advice is worth trading that
|
|
away.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect other contributors.</para>
|
|
|
|
<para>You were not always a committer. At one time you were
|
|
a contributor. Remember that at all times. Remember what
|
|
it was like trying to get help and attention. Do not
|
|
forget that your work as a contributor was very important
|
|
to you. Remember what it was like. Do not discourage,
|
|
belittle, or demean contributors. Treat them with
|
|
respect. They are our committers in waiting. They are
|
|
every bit as important to the project as committers.
|
|
Their contributions are as valid and as important as your
|
|
own. After all, you made many contributions before you
|
|
became a committer. Always remember that.</para>
|
|
|
|
<para>Consider the points raised under
|
|
<xref linkend="respect"/> and apply them also to
|
|
contributors.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Discuss any significant change
|
|
<emphasis>before</emphasis> committing.</para>
|
|
|
|
<para>The repository is not where changes should be
|
|
initially submitted for correctness or argued over, that
|
|
should happen first in the mailing lists and the commit
|
|
should only happen once something resembling consensus has
|
|
been reached. This does not mean that you have to ask
|
|
permission before correcting every obvious syntax error or
|
|
manual page misspelling, simply that you should try to
|
|
develop a feel for when a proposed change is not quite
|
|
such a no-brainer and requires some feedback first.
|
|
People really do not mind sweeping changes if the result
|
|
is something clearly better than what they had before,
|
|
they just do not like being <emphasis>surprized</emphasis>
|
|
by those changes. The very best way of making sure that
|
|
you are on the right track is to have your code reviewed
|
|
by one or more other committers.</para>
|
|
|
|
<para>When in doubt, ask for review!</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect existing maintainers if listed.</para>
|
|
|
|
<para>Many parts of &os; are not <quote>owned</quote> in
|
|
the sense that any specific individual will jump up and
|
|
yell if you commit a change to <quote>their</quote> area,
|
|
but it still pays to check first. One convention we use
|
|
is to put a maintainer line in the
|
|
<filename>Makefile</filename> for any package or subtree
|
|
which is being actively maintained by one or more people;
|
|
see <link xlink:href="&url.books.developers-handbook;/policies.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/policies.html</link>
|
|
for documentation on this. Where sections of code have
|
|
several maintainers, commits to affected areas by one
|
|
maintainer need to be reviewed by at least one other
|
|
maintainer. In cases where the
|
|
<quote>maintainer-ship</quote> of something is not clear,
|
|
you can also look at the repository logs for the file(s)
|
|
in question and see if someone has been working recently
|
|
or predominantly in that area.</para>
|
|
|
|
<para>Other areas of &os; fall under the control of
|
|
someone who manages an overall category of &os;
|
|
evolution, such as internationalization or networking.
|
|
See <link xlink:href="&url.base;/administration.html">http://www.FreeBSD.org/administration.html</link>
|
|
for more information on this.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Any disputed change must be backed out pending
|
|
resolution of the dispute if requested by a maintainer.
|
|
Security related changes may
|
|
override a maintainer's wishes at the Security Officer's
|
|
discretion.</para>
|
|
|
|
<para>This may be hard to swallow in times of conflict (when
|
|
each side is convinced that they are in the right, of
|
|
course) but a version control system makes it unnecessary
|
|
to have an ongoing dispute raging when it is far easier to
|
|
simply reverse the disputed change, get everyone calmed
|
|
down again and then try to figure out what is the best way
|
|
to proceed. If the change turns out to be the best thing
|
|
after all, it can be easily brought back. If it turns out
|
|
not to be, then the users did not have to live with the
|
|
bogus change in the tree while everyone was busily
|
|
debating its merits. People <emphasis>very</emphasis>
|
|
rarely call for back-outs in the repository since
|
|
discussion generally exposes bad or controversial changes
|
|
before the commit even happens, but on such rare occasions
|
|
the back-out should be done without argument so that we
|
|
can get immediately on to the topic of figuring out
|
|
whether it was bogus or not.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes go to &os.current; before &os.stable; unless
|
|
specifically permitted by the release engineer or unless
|
|
they are not applicable to &os.current;. Any non-trivial
|
|
or non-urgent change which is applicable should also be
|
|
allowed to sit in &os.current; for at least 3 days before
|
|
merging so that it can be given sufficient testing. The
|
|
release engineer has the same authority over the
|
|
&os.stable; branch as outlined in rule #5.</para>
|
|
|
|
<para>This is another <quote>do not argue about it</quote>
|
|
issue since it is the release engineer who is ultimately
|
|
responsible (and gets beaten up) if a change turns out to
|
|
be bad. Please respect this and give the release engineer
|
|
your full cooperation when it comes to the &os.stable;
|
|
branch. The management of &os.stable; may frequently seem
|
|
to be overly conservative to the casual observer, but also
|
|
bear in mind the fact that conservatism is supposed to be
|
|
the hallmark of &os.stable; and different rules apply
|
|
there than in &os.current;. There is also really no point
|
|
in having &os.current; be a testing ground if changes are
|
|
merged over to &os.stable; immediately. Changes need a
|
|
chance to be tested by the &os.current; developers, so
|
|
allow some time to elapse before merging unless the
|
|
&os.stable; fix is critical, time sensitive or so obvious
|
|
as to make further testing unnecessary (spelling fixes to
|
|
manual pages, obvious bug/typo fixes, etc.) In other
|
|
words, apply common sense.</para>
|
|
|
|
<para>Changes to the security branches (for example,
|
|
<literal>RELENG_7_0</literal>) must be approved by a
|
|
member of the &a.security-officer;, or in some cases, by a
|
|
member of the &a.re;.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Do not fight in public with other committers; it looks
|
|
bad. If you must <quote>strongly disagree</quote> about
|
|
something, do so only in private.</para>
|
|
|
|
<para>This project has a public image to uphold and that
|
|
image is very important to all of us, especially if we are
|
|
to continue to attract new members. There will be
|
|
occasions when, despite everyone's very best attempts at
|
|
self-control, tempers are lost and angry words are
|
|
exchanged. The best thing that can be done in such cases
|
|
is to minimize the effects of this until everyone has
|
|
cooled back down. That means that you should not air your
|
|
angry words in public and you should not forward private
|
|
correspondence to public mailing lists or aliases. What
|
|
people say one-to-one is often much less sugar-coated than
|
|
what they would say in public, and such communications
|
|
therefore have no place there - they only serve to inflame
|
|
an already bad situation. If the person sending you a
|
|
flame-o-gram at least had the grace to send it privately,
|
|
then have the grace to keep it private yourself. If you
|
|
feel you are being unfairly treated by another developer,
|
|
and it is causing you anguish, bring the matter up with
|
|
core rather than taking it public. Core will do its best
|
|
to play peace makers and get things back to sanity. In
|
|
cases where the dispute involves a change to the codebase
|
|
and the participants do not appear to be reaching an
|
|
amicable agreement, core may appoint a mutually-agreeable
|
|
3rd party to resolve the dispute. All parties involved
|
|
must then agree to be bound by the decision reached by
|
|
this 3rd party.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect all code freezes and read the
|
|
<literal>committers</literal> and
|
|
<literal>developers</literal> mailing list on a timely
|
|
basis so you know when a code freeze is in effect.</para>
|
|
|
|
<para>Committing unapproved changes during a code freeze is
|
|
a really big mistake and committers are expected to keep
|
|
up-to-date on what is going on before jumping in after a
|
|
long absence and committing 10 megabytes worth of
|
|
accumulated stuff. People who abuse this on a regular
|
|
basis will have their commit privileges suspended until
|
|
they get back from the &os; Happy Reeducation Camp we
|
|
run in Greenland.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When in doubt on any procedure, ask first!</para>
|
|
|
|
<para>Many mistakes are made because someone is in a hurry
|
|
and just assumes they know the right way of doing
|
|
something. If you have not done it before, chances are
|
|
good that you do not actually know the way we do things
|
|
and really need to ask first or you are going to
|
|
completely embarrass yourself in public. There is no
|
|
shame in asking
|
|
<quote>how in the heck do I do this?</quote> We already
|
|
know you are an intelligent person; otherwise, you would
|
|
not be a committer.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Test your changes before committing them.</para>
|
|
|
|
<!-- XXX Needs update re sparc64 + pc98
|
|
Also, needs more details on which machines are available for testing
|
|
-->
|
|
<para>This may sound obvious, but if it really were so
|
|
obvious then we probably would not see so many cases of
|
|
people clearly not doing this. If your changes are to the
|
|
kernel, make sure you can still compile both GENERIC and
|
|
LINT. If your changes are anywhere else, make sure you
|
|
can still make world. If your changes are to a branch,
|
|
make sure your testing occurs with a machine which is
|
|
running that code. If you have a change which also may
|
|
break another architecture, be sure and test on all
|
|
supported architectures. Please refer to the
|
|
<link xlink:href="http://www.FreeBSD.org/internal/">&os;
|
|
Internal Page</link> for a list of available resources.
|
|
As other architectures are added to the &os; supported
|
|
platforms list, the appropriate shared testing resources
|
|
will be made available.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Do not commit to anything under the
|
|
<filename>src/contrib</filename>,
|
|
<filename>src/crypto</filename>, and
|
|
<filename>src/sys/contrib</filename> trees without
|
|
<emphasis>explicit</emphasis> approval from the respective
|
|
maintainer(s).</para>
|
|
|
|
<para>The trees mentioned above are for contributed software
|
|
usually imported onto a vendor branch. Committing
|
|
something there, even if it does not take the file off the
|
|
vendor branch, may cause unnecessary headaches for those
|
|
responsible for maintaining that particular piece of
|
|
software. Thus, unless you have
|
|
<emphasis>explicit</emphasis> approval from the maintainer
|
|
(or you are the maintainer), do <emphasis>not</emphasis>
|
|
commit there!</para>
|
|
|
|
<para>Please note that this does not mean you should not try
|
|
to improve the software in question; you are still more
|
|
than welcome to do so. Ideally, you should submit your
|
|
patches to the vendor. If your changes are
|
|
&os;-specific, talk to the maintainer; they may be
|
|
willing to apply them locally. But whatever you do, do
|
|
<emphasis>not</emphasis> commit there by yourself!</para>
|
|
|
|
<para>Contact the &a.core; if you wish to take up
|
|
maintainership of an unmaintained part of the tree.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Policy on Multiple Architectures</title>
|
|
|
|
<para>&os; has added several new architecture ports during
|
|
recent release cycles and is truly no longer an &i386; centric
|
|
operating system. In an effort to make it easier to keep
|
|
&os; portable across the platforms we support, core has
|
|
developed the following mandate:</para>
|
|
|
|
<blockquote>
|
|
<para>Our 32-bit reference platform is &arch.i386;, and our
|
|
64-bit reference platform is &arch.sparc64;. Major design
|
|
work (including major API and ABI changes) must prove
|
|
itself on at least one 32-bit and at least one 64-bit
|
|
platform, preferably the primary reference platforms,
|
|
before it may be committed to the source tree.</para>
|
|
</blockquote>
|
|
|
|
<para>The &arch.i386; and &arch.sparc64; platforms were chosen
|
|
due to being more readily available to developers and as
|
|
representatives of more diverse processor and system designs -
|
|
big versus little endian, register file versus register stack,
|
|
different DMA and cache implementations, hardware page tables
|
|
versus software TLB management etc.</para>
|
|
|
|
<para>The &arch.ia64; platform has many of the same
|
|
complications that &arch.sparc64; has, but is still limited in
|
|
availability to developers.</para>
|
|
|
|
<para>We will continue to re-evaluate this policy as cost and
|
|
availability of the 64-bit platforms change.</para>
|
|
|
|
<para>Developers should also be aware of our Tier Policy for
|
|
the long term support of hardware architectures. The rules
|
|
here are intended to provide guidance during the development
|
|
process, and are distinct from the requirements for features
|
|
and architectures listed in that section. The Tier rules for
|
|
feature support on architectures at release-time are more
|
|
strict than the rules for changes during the development
|
|
process.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Other Suggestions</title>
|
|
|
|
<para>When committing documentation changes, use a spell checker
|
|
before committing. For all XML docs, you should also
|
|
verify that your formatting directives are correct by running
|
|
<command>make lint</command>.</para>
|
|
|
|
<para>For all on-line manual pages, run <command>manck</command>
|
|
(from ports) over the manual page to verify all of the cross
|
|
references and file references are correct and that the man
|
|
page has all of the appropriate <varname>MLINK</varname>s
|
|
installed.</para>
|
|
|
|
<para>Do not mix style fixes with new functionality. A style
|
|
fix is any change which does not modify the functionality of
|
|
the code. Mixing the changes obfuscates the functionality
|
|
change when asking for differences between revisions, which
|
|
can hide any new bugs. Do not include whitespace changes with
|
|
content changes in commits to <filename>doc/</filename> or
|
|
<filename>www/</filename>. The extra clutter in the diffs
|
|
makes the translators' job much more difficult. Instead, make
|
|
any style or whitespace changes in separate commits that are
|
|
clearly labeled as such in the commit message.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Deprecating Features</title>
|
|
|
|
<para>When it is necessary to remove functionality from software
|
|
in the base system the following guidelines should be followed
|
|
whenever possible:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Mention is made in the manual page and possibly the
|
|
release notes that the option, utility, or interface is
|
|
deprecated. Use of the deprecated feature generates a
|
|
warning.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The option, utility, or interface is preserved until
|
|
the next major (point zero) release.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The option, utility, or interface is removed and no
|
|
longer documented. It is now obsolete. It is also
|
|
generally a good idea to note its removal in the release
|
|
notes.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="archs">
|
|
<title>Support for Multiple Architectures</title>
|
|
|
|
<para>&os; is a highly portable operating system intended to
|
|
function on many different types of hardware architectures.
|
|
Maintaining clean separation of Machine Dependent (MD) and
|
|
Machine Independent (MI) code, as well as minimizing MD code, is
|
|
an important part of our strategy to remain agile with regards
|
|
to current hardware trends. Each new hardware architecture
|
|
supported by &os; adds substantially to the cost of code
|
|
maintenance, toolchain support, and release engineering. It
|
|
also dramatically increases the cost of effective testing of
|
|
kernel changes. As such, there is strong motivation to
|
|
differentiate between classes of support for various
|
|
architectures while remaining strong in a few key architectures
|
|
that are seen as the &os; <quote>target audience</quote>.</para>
|
|
|
|
<sect2>
|
|
<title>Statement of General Intent</title>
|
|
|
|
<para>The &os; Project targets "production quality commercial
|
|
off-the-shelf (COTS) workstation, server, and high-end
|
|
embedded systems". By retaining a focus on a narrow set of
|
|
architectures of interest in these environments, the &os;
|
|
Project is able to maintain high levels of quality, stability,
|
|
and performance, as well as minimize the load on various
|
|
support teams on the project, such as the ports team,
|
|
documentation team, security officer, and release engineering
|
|
teams. Diversity in hardware support broadens the options for
|
|
&os; consumers by offering new features and usage
|
|
opportunities (such as support for 64-bit CPUs, use in
|
|
embedded environments, etc.), but these benefits must always
|
|
be carefully considered in terms of the real-world maintenance
|
|
cost associated with additional platform support.</para>
|
|
|
|
<para>The &os; Project differentiates platform targets into
|
|
four tiers. Each tier includes a specification of the
|
|
requirements for an architecture to be in that tier,
|
|
as well as specifying the obligations of developers with
|
|
regards to the platform. In addition, a policy is defined
|
|
regarding the circumstances required to change the tier
|
|
of an architecture.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Tier 1: Fully Supported Architectures</title>
|
|
|
|
<para>Tier 1 platforms are fully supported by the security
|
|
officer, release engineering, and toolchain maintenance staff.
|
|
New features added to the operating system must be fully
|
|
functional across all Tier 1 architectures for every release
|
|
(features which are inherently architecture-specific, such as
|
|
support for hardware device drivers, may be exempt from this
|
|
requirement). In general, all Tier 1 platforms must have
|
|
build and Tinderbox support either in the FreeBSD.org cluster,
|
|
or be easily available for all developers. Embedded platforms
|
|
may substitute an emulator available in the &os; cluster
|
|
for actual hardware.</para>
|
|
|
|
<para>Tier 1 architectures are expected to be Production Quality
|
|
with respects to all aspects of the &os; operating system,
|
|
including installation and development environments.</para>
|
|
|
|
<para>Tier 1 architectures are expected to be completely
|
|
integrated into the source tree and have all features
|
|
necessary to produce an entire system relevant for that target
|
|
architecture. Tier 1 architectures generally have at least 6
|
|
active developers.</para>
|
|
|
|
<para>Tier 1 architectures are expected to be fully supported by
|
|
the ports system. All the ports should build on a Tier 1
|
|
platform, or have the appropriate filters to prevent the
|
|
inappropriate ones from building there. The packaging system
|
|
must support all Tier 1 architectures. To ensure an
|
|
architecture's Tier 1 status, proponents of that architecture
|
|
must show that all relevant packages can be built on that
|
|
platform.</para>
|
|
|
|
<para>Tier 1 embedded architectures must be able to cross-build
|
|
packages on at least one other Tier 1 architecture. The
|
|
packages must be the most relevant for the platform, but may
|
|
be a non-empty subset of those that build natively.</para>
|
|
|
|
<para>Tier 1 architectures must be fully documented. All basic
|
|
operations need to be covered by the handbook or other
|
|
documents. All relevant integration documentation must also
|
|
be integrated into the tree, or readily available.</para>
|
|
|
|
<para>Current Tier 1 platforms are &arch.i386; and
|
|
&arch.amd64;.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Tier 2: Developmental Architectures</title>
|
|
|
|
<para>Tier 2 platforms are not supported by the security officer
|
|
and release engineering teams. Platform maintainers are
|
|
responsible for toolchain support in the tree. The toolchain
|
|
maintainer is expected to work with the platform maintainers
|
|
to refine these changes. Major new toolchain components are
|
|
allowed to break support for Tier 2 architectures if the
|
|
&os;-local changes have not been incorporated upstream.
|
|
The toolchain maintainers are expected to provide prompt
|
|
review of any proposed changes and cannot block, through their
|
|
inaction, changes going into the tree. New features added to
|
|
&os; should be feasible to implement on these platforms,
|
|
but an implementation is not required before the feature may
|
|
be added to the &os; source tree. New features that may be
|
|
difficult to implement on Tier 2 architectures should provide
|
|
a means of disabling them on those architectures. The
|
|
implementation of a Tier 2 architecture may be committed to
|
|
the main &os; tree as long as it does not interfere with
|
|
production work on Tier 1 platforms, or substantially with
|
|
other Tier 2 platforms. Before a Tier 2 platform can be added
|
|
to the &os; base source tree, the platform must be able to
|
|
boot multi-user on actual hardware. Generally, there must be
|
|
at least three active developers working on the
|
|
platform.</para>
|
|
|
|
<para>Tier 2 architectures are usually systems targeted at Tier
|
|
1 support, but that are still under development.
|
|
Architectures reaching end of life may also be moved from Tier
|
|
1 status to Tier 2 status as the availability of resources to
|
|
continue to maintain the system in a Production Quality state
|
|
diminishes. Well supported niche architectures may also be
|
|
Tier 2.</para>
|
|
|
|
<para>Tier 2 architectures may have some support for them
|
|
integrated into the ports infrastructure. They may have cross
|
|
compilation support added, at the discretion of portmgr. Some
|
|
ports must built natively into packages if the package system
|
|
supports that architecture. If not integrated into the base
|
|
system, some external patches for the architecture for ports
|
|
must be available.</para>
|
|
|
|
<para>Tier 2 architectures can be integrated into the &os;
|
|
handbook. The basics for how to get a system running must be
|
|
documented, although not necessarily for every single board or
|
|
system a Tier 2 architecture supports. The supported hardware
|
|
list must exist and should be no more than a couple of months
|
|
old. It should be integrated into the &os;
|
|
documentation.</para>
|
|
|
|
<para>Current Tier 2 platforms are &arch.arm;, &arch.ia64;,
|
|
&arch.pc98;, &arch.powerpc;, and &arch.sparc64;.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Tier 3: Experimental Architectures</title>
|
|
|
|
<para>Tier 3 platforms are not supported by the security officer
|
|
and release engineering teams. At the discretion of the
|
|
toolchain maintainer, they may be supported in the toolchain.
|
|
Tier 3 platforms are architectures in the early stages of
|
|
development, for non-mainstream hardware platforms, or which
|
|
are considered legacy systems unlikely to see broad future
|
|
use. New Tier 3 systems will not be committed to the base
|
|
source tree. Support for Tier 3 systems may be worked on in
|
|
the &os; Perforce Repository, providing source control and
|
|
easier change integration from the main &os; tree.
|
|
Platforms that transition to Tier 3 status may be removed from
|
|
the tree if they are no longer actively supported by the
|
|
&os; developer community at the discretion of the release
|
|
engineer.</para>
|
|
|
|
<para>Tier 3 platforms may have ports support, either integrated
|
|
or external, but do not require it.</para>
|
|
|
|
<para>Tier 3 platforms must have the basics documented for how
|
|
to build a kernel and how to boot it on at least one target
|
|
hardware or emulation environment. This documentation need
|
|
not be integrated into the &os; tree.</para>
|
|
|
|
<para>Current Tier 3 platforms are &arch.mips; and
|
|
&s390;.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Tier 4: Unsupported Architectures</title>
|
|
|
|
<para>Tier 4 systems are not supported in any form by the
|
|
project.</para>
|
|
|
|
<para>All systems not otherwise classified into a support tier
|
|
are Tier 4 systems.</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Policy on Changing the Tier of an Architecture</title>
|
|
|
|
<para>Systems may only be moved from one tier to another by
|
|
approval of the &os; Core Team, which shall make that
|
|
decision in collaboration with the Security Officer, Release
|
|
Engineering, and toolchain maintenance teams.</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="ports">
|
|
<title>Ports Specific FAQ</title>
|
|
|
|
<qandaset>
|
|
<qandadiv>
|
|
<title>Adding a New Port</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I add a new port?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>First, please read the section about repository
|
|
copies.</para>
|
|
|
|
<para>The easiest way to add a new port is to use the
|
|
<command>addport</command> script from your machine
|
|
(located in the <filename>ports/Tools/scripts</filename>
|
|
directory). It will add a port from the directory you
|
|
specify, determining the category automatically from the
|
|
port <filename>Makefile</filename>. It will also add an
|
|
entry to the port's category
|
|
<filename>Makefile</filename>. It was written by
|
|
&a.mharo.email;, &a.will.email;, and &a.garga.email;.
|
|
When sending
|
|
questions about this script to the &a.ports;, please
|
|
also CC &a.crees.email;, the current maintainer.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>Any other things I need to know when I add a new
|
|
port?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Check the port, preferably to make sure it compiles
|
|
and packages correctly. This is the recommended
|
|
sequence:</para>
|
|
|
|
<screen>&prompt.root; <userinput>make install</userinput>
|
|
&prompt.root; <userinput>make package</userinput>
|
|
&prompt.root; <userinput>make deinstall</userinput>
|
|
&prompt.root; <userinput>pkg_add package you built above</userinput>
|
|
&prompt.root; <userinput>make deinstall</userinput>
|
|
&prompt.root; <userinput>make reinstall</userinput>
|
|
&prompt.root; <userinput>make package</userinput></screen>
|
|
|
|
<para>The <link xlink:href="&url.books.porters-handbook;/index.html">Porters
|
|
Handbook</link> contains more detailed
|
|
instructions.</para>
|
|
|
|
<para>Use &man.portlint.1; to check the syntax of the
|
|
port. You do not necessarily have to eliminate all
|
|
warnings but make sure you have fixed the simple
|
|
ones.</para>
|
|
|
|
<para>If the port came from a submitter who has not
|
|
contributed to the Project before, add that person's
|
|
name to the <link xlink:href="&url.articles.contributors;/contrib-additional.html">Additional
|
|
Contributors</link> section of the &os;
|
|
Contributors List.</para>
|
|
|
|
<para>Close the PR if the port came in as a PR. To close
|
|
a PR, just do <userinput>edit-pr
|
|
PR#</userinput> on
|
|
<systemitem>freefall</systemitem> and change the
|
|
<varname>state</varname> from <constant>open</constant>
|
|
to <constant>closed</constant>. You will be asked to
|
|
enter a log message and then you are done.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Removing an Existing Port</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I remove an existing port?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>First, please read the section about repository
|
|
copies. Before you remove the port, you have to verify
|
|
there are no other ports depending on it.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Make sure there is no dependency on the port
|
|
in the ports collection:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The port's PKGNAME should appear in exactly
|
|
one line in a recent INDEX file.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>No other ports should contain any reference
|
|
to the port's directory or PKGNAME in their
|
|
Makefiles</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Then, remove the port:</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>Remove the port's files and directory with
|
|
<command>svn remove</command>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Remove the <varname>SUBDIR</varname> listing
|
|
of the port in the parent directory
|
|
<filename>Makefile</filename>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Add an entry to
|
|
<filename>ports/MOVED</filename>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Remove the port from
|
|
<filename>ports/LEGAL</filename> if it is
|
|
there.</para>
|
|
</step>
|
|
</procedure>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Alternatively, you can use the
|
|
<command>rmport</command> script, from <filename>ports/Tools/scripts</filename>.
|
|
This script was written by &a.vd.email;. When sending
|
|
questions about this script to the &a.ports;, please
|
|
also CC &a.crees.email;, the current maintainer.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Re-adding a Deleted Port</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I re-add a deleted port?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>This is essentially the reverse of deleting a
|
|
port.</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>Figure out when the port was removed. Use this
|
|
<link xlink:href="http://people.freebsd.org/~crees/removed_ports/index.xml">list</link>
|
|
and then copy the last living revision of the port:
|
|
|
|
<screen>&prompt.user; <userinput>cd /usr/ports/category
|
|
</userinput>
|
|
&prompt.user; <userinput>svn cp 'svn+ssh://svn.freebsd.org/ports/category/portname/@{YYYY-MM-DD}' portname
|
|
</userinput></screen>
|
|
|
|
Pick a date that is before the removal but after the
|
|
last true commit.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Perform whatever changes are necessary to make
|
|
the port work again. If it was deleted because the
|
|
distfiles are no longer available you will need to
|
|
volunteer to host them yourself, or find someone
|
|
else to do so.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para><command>svn add</command> or
|
|
<command>svn remove</command> any appropriate
|
|
files.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Restore the <varname>SUBDIR</varname> listing of
|
|
the port in the parent directory
|
|
<filename>Makefile</filename>, and delete the entry
|
|
from <filename>ports/MOVED</filename>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>If the port had an entry in
|
|
<filename>ports/LEGAL</filename>, restore it.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para><command>svn commit</command> these changes,
|
|
preferably in one step.</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<tip>
|
|
<para><command>addport</command> now detects when the
|
|
port to add has previously existed, and should handle
|
|
all except the <filename>ports/LEGAL</filename> step
|
|
automatically.</para>
|
|
</tip>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Repository Copies</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>When do we need a repository copy?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>When you want to add a port that is related to
|
|
any port that is already in the tree in a separate
|
|
directory, you have to do a repository copy.
|
|
Here <wordasword>related</wordasword> means
|
|
it is a different version or a slightly modified
|
|
version. Examples are
|
|
<filename>print/ghostscript*</filename> (different
|
|
versions) and <filename>x11-wm/windowmaker*</filename>
|
|
(English-only and internationalized version).</para>
|
|
|
|
<para>Another example is when a port is moved from one
|
|
subdirectory to another, or when you want to change the
|
|
name of a directory because the author(s) renamed their
|
|
software even though it is a
|
|
descendant of a port already in a tree.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What do I need to do?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>With Subversion, a repo copy can be done by any
|
|
committer:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Doing a repo copy:</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>First make sure that you were using an up to
|
|
date ports tree and the target directory does
|
|
not exist.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Use <command>svn move</command> or
|
|
<command>svn copy</command> to do the repo
|
|
copy.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Upgrade the copied port to the new version.
|
|
Remember to change the
|
|
<varname>LATEST_LINK</varname> so there are no
|
|
duplicate ports with the same name. In some
|
|
rare cases it may be necessary to change the
|
|
<varname>PORTNAME</varname> instead of
|
|
<varname>LATEST_LINK</varname>, but this should
|
|
only be done when it is really needed —
|
|
e.g., using an existing port as the base for a
|
|
very similar program with a different name, or
|
|
upgrading a port to a new upstream version which
|
|
actually changes the distribution name, like the
|
|
transition from
|
|
<filename>textproc/libxml</filename> to
|
|
<filename>textproc/libxml2</filename>. In most
|
|
cases, changing <varname>LATEST_LINK</varname>
|
|
should suffice.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Add the new subdirectory to the
|
|
<varname>SUBDIR</varname> listing in the parent
|
|
directory <filename>Makefile</filename>. You
|
|
can run <command>make checksubdirs</command> in
|
|
the parent directory to check this.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>If the port changed categories, modify the
|
|
<varname>CATEGORIES</varname> line of the port's
|
|
<filename>Makefile</filename> accordingly</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Add an entry to
|
|
<filename>ports/MOVED</filename>, if you remove
|
|
the original port.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Commit all changes on one commit.</para>
|
|
</step>
|
|
</procedure>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When removing a port:</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>Perform a thorough check of the ports
|
|
collection for any dependencies on the old port
|
|
location/name, and update them. Running
|
|
<command>grep</command> on
|
|
<filename>INDEX</filename> is not enough because
|
|
some ports have dependencies enabled by
|
|
compile-time options. A full
|
|
<command>grep -r</command> of the ports
|
|
collection is recommended.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Remove the old port and the
|
|
old <varname>SUBDIR</varname> entry.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Add an entry to
|
|
<filename>ports/MOVED</filename>.</para>
|
|
</step>
|
|
</procedure>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>After repo moves (<quote>rename</quote>
|
|
operations where a port is copied and the old
|
|
location is removed):</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>Follow the same steps that are outlined in
|
|
the previous two entries, to activate the new
|
|
location of the port and remove the old
|
|
one.</para>
|
|
</step>
|
|
</procedure>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Ports Freeze</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What is a <quote>ports freeze</quote>?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Before a release, it is necessary to restrict
|
|
commits to the ports tree for a short period of time
|
|
while the packages and the release itself are being
|
|
built. This is to ensure consistency among the various
|
|
parts of the release, and is called the
|
|
<quote>ports freeze</quote>.</para>
|
|
|
|
<para>For more information on the background and
|
|
policies surrounding a ports freeze, see the
|
|
<link xlink:href="&url.base;/portmgr/qa.html">Portmgr
|
|
Quality Assurance page</link>.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What is a <quote>ports slush</quote> or
|
|
<quote>feature freeze</quote>?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>During a release cycle the ports tree may be in a
|
|
<quote>slush</quote> state instead of in a hard freeze.
|
|
The goal during a slush is to reach a stable ports tree
|
|
to avoid rebuilding large sets of packages for the
|
|
release and to tag the tree. During this time
|
|
<quote>sweeping changes</quote> are prohibited unless
|
|
specifically permitted by portmgr. Complete details
|
|
about what qualifies as a sweeping change can be found
|
|
on the <link xlink:href="&url.base;/portmgr/implementation.html">Portmgr
|
|
Implementation page</link>.</para>
|
|
|
|
<para>The benefit of a slush as opposed to a complete
|
|
freeze is that it allows maintainers to continue adding
|
|
new ports, making routine version updates, and bug fixes
|
|
to most existing ports, as long as the number of
|
|
affected ports is minimal. For example, updating the
|
|
shared library version on a port that many other ports
|
|
depend on.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How long is a ports freeze or slush?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>A freeze only lasts long enough to tag the tree.
|
|
A slush usually lasts a week or two, but may last
|
|
longer.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What does it mean to me?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>During a ports freeze, you are not allowed to
|
|
commit anything to the tree without explicit approval
|
|
from the Ports Management Team. <quote>Explicit
|
|
approval</quote> here means that you send a patch to
|
|
the Ports Management Team for review and get a reply
|
|
saying, <quote>Go ahead and commit it.</quote></para>
|
|
|
|
<para>Not everything is allowed to be committed during
|
|
a freeze. Please see the <link xlink:href="&url.base;/portmgr/qa.html">Portmgr Quality
|
|
Assurance page</link> for more information.</para>
|
|
|
|
<para>Note that you do not have implicit permission to fix
|
|
a port during the freeze just because it is
|
|
broken.</para>
|
|
|
|
<para>During a ports slush, you are still allowed to
|
|
commit but you must exercise more caution in what you
|
|
commit. Furthermore a special note (typically
|
|
<quote>Feature Safe: yes</quote>) must be added to the
|
|
commit message.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I know when the ports slush starts?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>The Ports Management Team will send out warning
|
|
messages to the &a.ports; and &a.committers;
|
|
announcing the start of the impending release, usually
|
|
two or three weeks in advance. The exact starting time
|
|
will not be determined until a few days before the
|
|
actual release. This is because the ports slush has to
|
|
be synchronized with the release, and it is usually not
|
|
known until then when exactly the release will be
|
|
rolled.</para>
|
|
|
|
<para>When the slush starts, there will be another
|
|
announcement to the &a.ports; and &a.committers;, of
|
|
course.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I know when the freeze or slush ends?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>A few hours after the release, the Ports Management
|
|
Team will send out a mail to the &a.ports; and
|
|
&a.committers; announcing the end of the ports freeze or
|
|
slush. Note that the release being cut does not
|
|
automatically indicate the end of the freeze. We have
|
|
to make sure there will be no last minute snafus that
|
|
result in an immediate re-rolling of the release.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Creating a New Category</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What is the procedure for creating a new
|
|
category?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Please see <link xlink:href="&url.books.porters-handbook;/makefile-categories.html#PROPOSING-CATEGORIES">
|
|
Proposing a New Category</link> in the Porter's
|
|
Handbook. Once that procedure has been followed and the
|
|
PR has been assigned to &a.portmgr;, it is their
|
|
decision whether or not to approve it. If they do, it
|
|
is their responsibility to do the following:</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>Perform any needed moves. (This only applies
|
|
to physical categories.)</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Update the <varname>VALID_CATEGORIES</varname>
|
|
definition in
|
|
<filename>ports/Mk/bsd.port.mk</filename>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Assign the PR back to you.</para>
|
|
</step>
|
|
</procedure>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What do I need to do to implement a new physical
|
|
category?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<procedure>
|
|
<step>
|
|
<para>Upgrade each moved port's
|
|
<filename>Makefile</filename>. Do not connect the
|
|
new category to the build yet.</para>
|
|
|
|
<para>To do this, you will need to:</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>Change the port's
|
|
<varname>CATEGORIES</varname> (this was the
|
|
point of the exercise, remember?) The new
|
|
category should be listed
|
|
<emphasis>first</emphasis>. This will help to
|
|
ensure that the <varname>PKGORIGIN</varname> is
|
|
correct.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Run a <command>make describe</command>.
|
|
Since the top-level
|
|
<command>make index</command> that you will be
|
|
running in a few steps is an iteration of
|
|
<command>make describe</command> over the entire
|
|
ports hierarchy, catching any errors here will
|
|
save you having to re-run that step later
|
|
on.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>If you want to be really thorough, now
|
|
might be a good time to run
|
|
&man.portlint.1;.</para>
|
|
</step>
|
|
</procedure>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Check that the <varname>PKGORIGIN</varname>s are
|
|
correct. The ports system uses each port's
|
|
<varname>CATEGORIES</varname> entry to create its
|
|
<varname>PKGORIGIN</varname>, which is used to
|
|
connect installed packages to the port directory
|
|
they were built from. If this entry is wrong,
|
|
common port tools like &man.pkg.version.1; and
|
|
&man.portupgrade.1; fail.</para>
|
|
|
|
<para>To do this, use the
|
|
<filename>chkorigin.sh</filename> tool, as follows:
|
|
<command>env
|
|
PORTSDIR=/path/to/ports
|
|
sh -e
|
|
/path/to/ports/Tools/scripts/chkorigin.sh</command>.
|
|
This will check <emphasis>every</emphasis> port in
|
|
the ports tree, even those not connected to the
|
|
build, so you can run it directly after the move
|
|
operation. Hint: do not forget to look at the
|
|
<varname>PKGORIGIN</varname>s of any slave ports of
|
|
the ports you just moved!</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>On your own local system, test the proposed
|
|
changes: first, comment out the
|
|
<varname>SUBDIR</varname> entries in the old ports'
|
|
categories' <filename>Makefile</filename>s; then
|
|
enable building the new category in
|
|
<filename>ports/Makefile</filename>. Run
|
|
<command>make checksubdirs</command> in the affected
|
|
category directories to check the
|
|
<varname>SUBDIR</varname> entries. Next, in the
|
|
<filename>ports/</filename>
|
|
directory, run <command>make index</command>. This
|
|
can take over 40 minutes on even modern systems;
|
|
however, it is a necessary step to prevent problems
|
|
for other people.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Once this is done, you can commit the updated
|
|
<filename>ports/Makefile</filename> to connect the
|
|
new category to the build and also commit the
|
|
<filename>Makefile</filename> changes for the old
|
|
category or categories.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Add appropriate entries to
|
|
<filename>ports/MOVED</filename>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Update the documentation by modifying the
|
|
following:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>the <link xlink:href="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">list
|
|
of categories</link> in the Porter's
|
|
Handbook</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<filename>www/en/ports/categories</filename>.
|
|
Note that these are now displayed by sub-groups,
|
|
as specified in
|
|
<filename>www/en/ports/categories.descriptions</filename>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>(Note: these are in the docs, not the ports,
|
|
repository). If you are not a docs committer, you
|
|
will need to submit a PR for this.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Only once all the above have been done, and no
|
|
one is any longer reporting problems with the new
|
|
ports, should the old ports be deleted from their
|
|
previous locations in the repository.</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<para>It is not necessary to manually update the
|
|
<link xlink:href="&url.base;/ports/index.html">ports web
|
|
pages</link> to reflect the new category. This is
|
|
now done automatically via your change to
|
|
<filename>www/en/ports/categories</filename> and the
|
|
daily automated rebuild of
|
|
<filename>INDEX</filename>.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What do I need to do to implement a new virtual
|
|
category?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>This is much simpler than a physical category. You
|
|
only need to modify the following:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>the <link xlink:href="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">list
|
|
of categories</link> in the Porter's
|
|
Handbook</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><filename>www/en/ports/categories</filename></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Miscellaneous Questions</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I know if my port is building correctly or
|
|
not?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>First, go check <uri xlink:href="http://pointyhat.FreeBSD.org/errorlogs/">http://pointyhat.FreeBSD.org/errorlogs/</uri>.
|
|
There you will find error logs from the latest package
|
|
building runs on all supported platforms for the most
|
|
recent branches.</para>
|
|
|
|
<para>However, just because the port does not show up
|
|
there does not mean it is building correctly. (One of
|
|
the dependencies may have failed, for instance.) The
|
|
relevant directories are available on
|
|
<systemitem>pointyhat</systemitem> under <filename>/a/portbuild/<arch>/<major_version></filename>
|
|
so feel free to dig around. Each architecture and
|
|
version has the following subdirectories:</para>
|
|
|
|
<programlisting>errors error logs from latest <major_version> run on <arch>
|
|
logs all logs from latest <major_version> run on <arch>
|
|
packages packages from latest <major_version> run on <arch>
|
|
bak/errors error logs from last complete <major_version> run on <arch>
|
|
bak/logs all logs from last complete <major_version> run on <arch>
|
|
bak/packages packages from last complete <major_version> run on <arch></programlisting>
|
|
|
|
<para>Basically, if the port shows up in
|
|
<filename>packages</filename>, or it is in
|
|
<filename>logs</filename> but not in
|
|
<filename>errors</filename>, it built fine. (The
|
|
<filename>errors</filename> directories are what you get
|
|
from the web page.)</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>I added a new port. Do I need to add it to the
|
|
<filename>INDEX</filename>?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>No. The file can either be generated
|
|
by running <command>make index</command>, or a
|
|
pre-generated version can be downloaded with
|
|
<command>make fetchindex</command>.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>Are there any other files I am not allowed to
|
|
touch?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Any file directly under <filename>ports/</filename>,
|
|
or any file under a subdirectory that starts with an
|
|
uppercase letter (<filename>Mk/</filename>,
|
|
<filename>Tools/</filename>, etc.). In particular, the
|
|
Ports Management Team is very protective of
|
|
<filename>ports/Mk/bsd.port*.mk</filename> so do not
|
|
commit changes to those files unless you want to face
|
|
their wra(i)th.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What is the proper procedure for updating the
|
|
checksum for a port's distfile when the file changes
|
|
without a version change?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>When the checksum for a port's distfile is updated
|
|
due to the author updating the file without changing the
|
|
port's revision, the commit message should include a
|
|
summary of the relevant diffs between the original and
|
|
new distfile to ensure that the distfile has not been
|
|
corrupted or maliciously altered. If the current
|
|
version of the port has been in the ports tree for a
|
|
while, a copy of the old distfile will usually be
|
|
available on the ftp servers; otherwise the author or
|
|
maintainer should be contacted to find out why the
|
|
distfile has changed.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
</qandaset>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="non-committers">
|
|
<title>Issues Specific to Developers Who Are Not
|
|
Committers</title>
|
|
|
|
<para>A few people who have access to the &os; machines do not
|
|
have commit bits. For instance, the project is willing to give
|
|
access to the GNATS database to contributors who have shown
|
|
interest and dedication in working on Problem Reports.</para>
|
|
|
|
<para>Almost all of this document will apply to these developers
|
|
as well (except things specific to commits and the mailing list
|
|
memberships that go with them). In particular, we recommend
|
|
that you read:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><link linkend="admin">Administrative
|
|
Details</link></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><link linkend="conventions-everyone">Conventions</link></para>
|
|
|
|
<note>
|
|
<para>You should get your mentor to add you to the
|
|
<quote>Additional Contributors</quote>
|
|
(<filename>doc/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename>),
|
|
if you are not already listed there.</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><link linkend="developer.relations">Developer
|
|
Relations</link></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><link linkend="ssh.guide">SSH Quick-Start
|
|
Guide</link></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><link linkend="rules">The &os; Committers' Big List
|
|
of Rules</link></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</sect1>
|
|
|
|
<sect1 xml:id="google-analytics">
|
|
<title>Information About &ga;</title>
|
|
|
|
<para>As of December 12, 2012, &ga; was enabled on the
|
|
&os; Project website to collect anonymized usage statistics
|
|
regarding usage of the site. The information collected is
|
|
valuable to the &os; Documentation Project, in order to
|
|
identify various problems on the &os; website.</para>
|
|
|
|
<sect2 xml:id="google-analytics-policy">
|
|
<title>&ga; General Policy</title>
|
|
|
|
<para>The &os; Project takes visitor privacy very
|
|
seriously. As such, the &os; Project website honors the
|
|
<quote>Do Not Track</quote> header <emphasis>before</emphasis>
|
|
fetching the tracking code from Google. For more information,
|
|
please see the
|
|
<link xlink:href="http://www.FreeBSD.org/privacy.html">&os; Privacy
|
|
Policy</link>.</para>
|
|
|
|
<para>&ga; access is <emphasis>not</emphasis> arbitrarily
|
|
allowed — access must be requested, voted on by the
|
|
&a.doceng;, and explicitly granted.</para>
|
|
|
|
<para>Requests for &ga; data must include a specific purpose.
|
|
For example, a valid reason for requesting access would be
|
|
<quote>to see the most frequently used web browsers when
|
|
viewing &os; web pages to ensure page rendering speeds are
|
|
acceptable.</quote></para>
|
|
|
|
<para>Conversely, <quote>to see what web browsers are most
|
|
frequently used</quote> (without stating
|
|
<emphasis>why</emphasis>) would be rejected.</para>
|
|
|
|
<para>All requests must include the timeframe for which the data
|
|
would be required. For example, it must be explicitly stated
|
|
if the requested data would be needed for a timeframe covering
|
|
a span of 3 weeks, or if the request would be one-time
|
|
only.</para>
|
|
|
|
<para>Any request for &ga; data without a clear, reasonable
|
|
reason beneficial to the &os; Project will be
|
|
rejected.</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="google-analytics-data">
|
|
<title>Data Available Through &ga;</title>
|
|
|
|
<para>A few examples of the types of &ga; data available
|
|
include:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Commonly used web browsers</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Page load times</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Site access by language</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="perks">
|
|
<title>Perks of the Job</title>
|
|
|
|
<para>Unfortunately, there are not many perks involved with being
|
|
a committer. Recognition as a competent software engineer is
|
|
probably the only thing that will be of benefit in the long run.
|
|
However, there are at least some perks:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Free 4-CD and DVD Sets</term>
|
|
|
|
<listitem>
|
|
<para>&os; committers can get a free 4-CD or DVD set at
|
|
conferences from <link xlink:href="http://www.freebsdmall.com">
|
|
&os; Mall, Inc.</link>. The sets are no longer
|
|
available as a subscription due to the high shipment costs
|
|
to countries outside the USA.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Freenode IRC Cloaks</term>
|
|
|
|
<listitem>
|
|
<para>&os; developers may request a cloaked hostmask for
|
|
their account on the Freenode IRC network in the form of
|
|
<literal>freebsd/developer/</literal><replaceable>freefall
|
|
name</replaceable> or
|
|
<literal>freebsd/developer/</literal><replaceable>NickServ
|
|
name</replaceable>. To request a cloak, send an email to
|
|
&a.eadler.email; with your requested hostmask and NickServ
|
|
account name.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="misc">
|
|
<title>Miscellaneous Questions</title>
|
|
|
|
<qandaset>
|
|
<qandaentry>
|
|
<question>
|
|
<para>Why are trivial or cosmetic changes to files on a
|
|
vendor branch a bad idea?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>From now on, every new vendor release of that file
|
|
will need to have patches merged in by hand.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>From now on, every new vendor release of that file
|
|
will need to have patches
|
|
<emphasis>verified</emphasis> by hand.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I add a new file to a branch?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>To add a file onto a branch, simply checkout or update
|
|
to the branch you want to add to and then add the file
|
|
using the add operation as you normally would. This works
|
|
fine for the <literal>doc</literal> and
|
|
<literal>ports</literal> trees. The
|
|
<literal>src</literal> tree uses SVN and requires more
|
|
care because of the <literal>mergeinfo</literal>
|
|
properties. See section 1.4.6 of the <link xlink:href="http://wiki.freebsd.org/SubversionPrimer">Subversion
|
|
Primer</link> for details. Refer to <link xlink:href="http://wiki.freebsd.org/SubversionPrimer/Merging">SubversionPrimer/Merging</link>
|
|
for details on how to perform an MFC.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I access
|
|
<systemitem class="fqdomainname">people.FreeBSD.org</systemitem> to put up
|
|
personal or project information?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para><systemitem class="fqdomainname">people.FreeBSD.org</systemitem> is the
|
|
same as
|
|
<systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem>. Just
|
|
create a <filename>public_html</filename> directory.
|
|
Anything you place in that directory will automatically be
|
|
visible under <uri xlink:href="http://people.FreeBSD.org/">http://people.FreeBSD.org/</uri>.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>Where are the mailing list archives stored?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>The mailing lists are archived under
|
|
<filename>/g/mail</filename> which will show up as
|
|
<filename>/hub/g/mail</filename> with &man.pwd.1;. This
|
|
location is accessible from any machine on the &os;
|
|
cluster.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>I would like to mentor a new committer. What process
|
|
do I need to follow?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>See the <link xlink:href="http://www.freebsd.org/internal/new-account.html">New
|
|
Account Creation Procedure</link> document on the
|
|
internal pages.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandaset>
|
|
</sect1>
|
|
</article>
|