Page MenuHomeFreeBSD
Files F176949809

D9981.1793644076.diff
No OneTemporary
Actions

Authored By
Unknown
Size
331 KB
Referenced Files
None
Subscribers
None

D9981.1793644076.diff
View Options

This file is larger than 256 KB, so syntax highlighting was skipped.
Index: en_US.ISO8859-1/articles/committers-guide/article.xml
===================================================================
--- en_US.ISO8859-1/articles/committers-guide/article.xml
+++ en_US.ISO8859-1/articles/committers-guide/article.xml
@@ -1,6 +1,6 @@
<?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" [
+ "http://www.freebsd.org/XML/share/xml/freebsd50.dtd" [
<!ENTITY ga "Google Analytics">
]>
@@ -9,7 +9,7 @@
xml:lang="en">
<info>
- <title>Committer's Guide</title>
+ <title>FreeBSD Committer's Guide</title>
<author>
<orgname>The &os; Documentation Project</orgname>
@@ -35,6 +35,7 @@
<year>2015</year>
<year>2016</year>
<year>2017</year>
+
<holder>The &os; Documentation Project</holder>
</copyright>
@@ -52,178 +53,771 @@
<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>
+ <para>Welcome to &os;! This onboarding guide provides new &os;
+ committers, contributors, GSoC students, and other project
+ community members with the procedures, policies and tools
+ required to commit to the various &os; source repositories.
+ While not every section of this guide will apply to every new
+ community member, every project participant is encouraged to
+ grow their project participation in conjunction with the
+ growth of their technical abilities. Existing committers are
+ strongly encouraged to review this guide from time to time and
+ committers who would like to mentor a new committer should
+ refer to the <link
+ xlink:href="http://www.freebsd.org/internal/new-account.html">New
+ Account Creation Procedure</link> page for guidance.</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>
+ <sect1 xml:id="benefits">
+ <title>Benefits of &os; Project Participation</title>
- <row>
- <entry><emphasis><literal>src/</literal> Subversion
- Root</emphasis></entry>
- <entry><literal>svn+ssh://</literal><systemitem
- class="fqdomainname">repo.FreeBSD.org</systemitem><filename>/base</filename>
- (see also <xref
- linkend="svn-getting-started-base-layout"/>).</entry>
- </row>
+ <sect2 xml:id="benefits-recognition">
+ <title>Recognition</title>
- <row>
- <entry><emphasis><literal>doc/</literal> Subversion
- Root</emphasis></entry>
- <entry><literal>svn+ssh://</literal><systemitem
- class="fqdomainname">repo.FreeBSD.org</systemitem><filename>/doc</filename>
- (see also <xref
- linkend="svn-getting-started-doc-layout"/>).</entry>
- </row>
+ <para>Recognition as an open source software contributor is the
+ longest lasting benefit of contributing to &os;. The &os;
+ project has brought together contributors from around the world
+ for over 20 years under three generations of leadership. &os;
+ is a complete operating system for various computing
+ architectures with a welcoming community that focuses on
+ tecnological innovation, flexibility and performance.
+ Additional benefits of contributing to &os; include:</para>
+ </sect2>
- <row>
- <entry><emphasis><literal>ports/</literal> Subversion
- Root</emphasis></entry>
+ <sect2 xml:id="benefits-freebsdmall">
+ <title>FreeBSD Mall Discs</title>
+
+ <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>.</para>
+ </sect2>
+
+ <sect2 xml:id="benefits-irc">
+ <title>Freenode <acronym>IRC</acronym> cloked hostmasks</title>
+
+ <para>In addition, 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.irc.email; with your requested hostmask and NickServ
+ account name.</para>
+ </sect2>
- <entry><literal>svn+ssh://</literal><systemitem
- class="fqdomainname">repo.FreeBSD.org</systemitem><filename>/ports</filename>
- (see also <xref
- linkend="svn-getting-started-ports-layout"/>).</entry>
- </row>
+ <sect2 xml:id="benefits-gandi">
+ <title>Gandi.net Discounts</title>
- <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 can
- be found in the files
- <filename>/local/mail/<replaceable>repository-name</replaceable>-developers-archive</filename>
- and
- <filename>/local/mail/<replaceable>repository-name</replaceable>-committers-archive</filename>
- on the <systemitem
- class="fqdomainname">FreeBSD.org</systemitem>
- cluster.)</entry>
- </row>
+ <para>Gandi provides website hosting, cloud computing, domain
+ registration, and X.509 certificate services.</para>
+ <para>Gandi offers an E-rate discount to all &os; developers.
+ Send mail to <email>non-profit@gandi.net</email> using your
+ <literal>@freebsd.org</literal> mail address, and indicate
+ your Gandi handle.</para>
+ </sect2>
+ </sect1>
- <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>
+ <sect1 xml:id="committer.types">
+ <title>Commit Bit Types</title>
- <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>
+ <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>
- <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>
+ <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/, ports/, src/ documentation</entry>
+ </row>
+
+ <row>
+ <entry>ports</entry>
+ <entry>portmgr@</entry>
+ <entry>ports/</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>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>Useful links:</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>
- <itemizedlist>
- <listitem>
- <para><link xlink:href="&url.base;/internal/">&os;
- Project Internal Pages</link></para>
- </listitem>
+ <sect2>
+ <title>Policy for Committer Activity in Other Trees</title>
- <listitem>
- <para><link
- xlink:href="&url.base;/internal/machines.html">&os;
- Project Hosts</link></para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>All committers may modify
+ <filename>base/head/share/misc/committers-*.dot</filename>,
+ <filename>base/head/usr.bin/calendar/calendars/calendar.freebsd</filename>,
+ and
+ <filename>ports/head/astro/xearth/files</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>doc committers may commit
+ documentation changes to <filename>src</filename>
+ 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>Any committer may make changes to any other tree
+ with an "Approved by" from a non-mentored committer with
+ the appropriate bit.</para>
+ </listitem>
+
+ <listitem>
+ <para>Committers can aquire an additional bit by the usual
+ process of finding a mentor who will propose them to core,
+ doceng, or portmgr, as appropriate. 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>
- <listitem>
- <para><link xlink:href="&url.base;/administration.html">&os;
- Project Administrative Groups</link></para>
- </listitem>
- </itemizedlist>
+ <sect1 xml:id="conventions">
+ <title>New Project Participant Setup, Conventions, and
+ Traditions</title>
+
+ <para>There are a number of things to do as a new developer.
+ The first set of steps is specific to committers only. These
+ steps must be done by a mentor for those who are not
+ committers.</para>
+
+ <sect2 xml:id="mentors">
+ <title>Mentors</title>
+
+ <para>All new developers have a mentor assigned to them for
+ the first few months. A mentor is responsible for teaching
+ the mentee the rules and conventions of the project and
+ guiding their first steps in the developer community. The
+ mentor is also personally responsible for the mentee's actions
+ during this initial period.</para>
+
+ <para>For committers: do not commit anything without first
+ getting mentor approval. Document that approval with an
+ <literal>Approved by:</literal> line in the commit
+ message.</para>
+
+ <para>When the mentor decides that a mentee has learned the
+ ropes and is ready to commit on their own, the mentor
+ announces it with a commit to
+ <filename>conf/mentors</filename>. This file is in the
+ <filename>svnadmin</filename> branch of each
+ repository:</para>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><literal>src</literal></entry>
+ <entry><filename>base/svnadmin/conf/mentors</filename></entry>
+ </row>
+
+ <row>
+ <entry><literal>doc</literal></entry>
+ <entry><filename>doc/svnadmin/conf/mentors</filename></entry>
+ </row>
+
+ <row>
+ <entry><literal>ports</literal></entry>
+ <entry><filename>ports/svnadmin/conf/mentors</filename></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 xml:id="devenv">
+ <title>Development Environment</title>
+
+ <para>&os; contributors are encouraged to contribute to the project
+ using a &os; development environment. &os; is a self-hosted
+ operating system with a wide array of available graphical desktops
+ and contributing to &os; <emphasis>using</emphasis> &os; is the
+ most efficient way of identifying and resolving any issues you may
+ encounter. The myriad of available virtualization options make
+ this easier than ever if a bare-metal &os; system is not available
+ to you. See the <link xlink:href="&url.base;/handbook/bsdinstall.html">Installing &os;</link>
+ section of the FreeBSD Handbook for information on installing &os;
+ </para>
+ </sect2>
+
+ <sect2 xml:id="conventions-committers">
+ <title>Setup Procedures for New Committers and Contributors</title>
+
+ <para>The fictional user "J. Random User &lt;jru@freebsd.org&gt;"
+ will be used in these instructions. Replace jru's information
+ with your name and usrename as appropriate.</para>
+
+ <para>Those who have been given commit rights to the &os;
+ repositories must follow these steps.</para>
+
+ <itemizedlist xml:id="commit-notes">
+ <listitem>
+ <para>Get mentor approval before committing each of these
+ changes!</para>
+ </listitem>
+
+ <listitem>
+ <para>The <filename>.ent</filename> and
+ <filename>.xml</filename> files mentioned below exist in
+ the &os; Documentation Project SVN repository at <link
+ xlink:href="svn.freebsd.org/doc/"><literal>svn.freebsd.org/doc/</literal></link>.</para>
+ </listitem>
+
+ <listitem>
+ <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. Verify that
+ <filename>~/.subversion/config</filename> contains the
+ necessary <quote>auto-props</quote> entries from
+ <filename>auto-props.txt</filename> mentioned
+ there.</para>
+ </listitem>
+
+ <listitem>
+ <para>All <filename>src</filename> commits should go to
+ &os.current; first before being merged to &os.stable;.
+ The &os.stable; branch must maintain
+ <acronym>ABI</acronym> and <acronym>API</acronym>
+ compatibility with earlier versions of that branch. Do
+ not merge changes that break this compatibility.</para>
+ </listitem>
+ </itemizedlist>
+
+ <procedure xml:id="commit-steps">
+ <title>Steps for New Committers and Contributors</title>
+
+ <step>
+ <title>Add an Author !ENTITY Entry</title>
+
+ <para>Committers: Add an author !ENTITY entry to
+ <filename>doc/head/share/xml/authors.ent</filename>.
+ This is an XML element that is used throughout the &os;
+ build system. Later steps depend on this entity, and
+ missing this step will cause the <filename>doc/</filename>
+ build to fail. This is a relatively easy task, but remains
+ a good first test of version control skills. Entries are
+ sorted by @freebsd.org username.</para>
+
+ <screen>
+...
+&lt;!ENTITY a.dexter "J. Random User"&gt;
+&lt;!ENTITY a.jru.email "&amp;a.jru; &lt;email xmlns='http://docbook.org/ns/docbook'&gt;jru@FreeBSD.org&lt;/email>"&gt;
+...
+ </screen>
+
+ </step>
+
+ <step>
+ <title>Update the List of Developers or Contributors</title>
+
+ <para>
+ Committers: Add an entry to the <quote>Developers</quote> section
+ of
+<filename>doc/head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename>
+ to appear on the <link
+ xlink:href="&url.articles.contributors;/staff-committers.html">Contributors
+ List</link>. Entries are sorted by last name.</para>
+
+ <screen>
+...
+ &lt;listitem&gt;
+ &lt;para&gt;&amp;a.jru.email;&lt;/para&gt;
+ &lt;/listitem&gt;
+...
+ </screen>
+
+ <para>Contributors becoming Committers: Transfer your !ENTITY
+ entry from the <quote>Additional Contributors</quote> to the
+ <quote>Developers</quote> section.</para>
+ </step>
+
+ <step>
+ <title>Add a News Item</title>
+
+ <para>Add a News Item entry to
+ <filename>doc/head/share/xml/news.xml</filename>
+ Look for the other entries that announce new committers and
+ follow the format. Use the date from the commit bit approval
+ email from <email>core@freebsd.org</email>.</para>
+
+<screen>
+...
+ &lt;month&gt;
+ &lt;name&gt;9&lt;/name&gt;
+
+ &lt;day&gt;
+ &lt;name&gt;23&lt;/name&gt;
+
+ &lt;event&gt;
+ &lt;p&gt;New committer:
+ &lt;a href="mailto:jru@FreeBSD.org"&gt;J. Random User&lt;/a&gt;
+ (doc)&lt;/p&gt;
+ &lt;/event&gt;
+ &lt;/day&gt;
+ &lt;/month&gt;
+...
+</screen>
+ </step>
+
+ <step>
+ <title>Add a <acronym>PGP</acronym>/<acronym>GnuPG</acronym> Key</title>
+
+ <para>If you do not have a
+ <acronym>PGP</acronym>/<acronym>GnuPG</acronym> key or your key
+ is expiring relatively soon, refer to
+ <xref linkend="pgpkeys-creating"/> for instructions on how to
+ create a new <acronym>PGP</acronym>/<acronym>GnuPG</acronym>
+ key.</para>
+
+ <para>Add your <acronym>PGP</acronym>/<acronym>GnuPG</acronym>
+ key to
+ <filename>doc/head/share/pgpkeys/pgpkeys.ent</filename>
+ and
+ <filename>doc/head/share/pgpkeys/pgpkeys-developers.xml</filename>
+ using the
+ <filename>doc/head/share/pgpkeys/addkey.sh</filename> shell
+ script. See <link
+ xlink:href="http://svnweb.freebsd.org/doc/head/share/pgpkeys/README">README</link>
+ file for full details. Note the instructions provided by
+ the script.</para>
+
+ <screen>&prompt.user; <userinput>./addkey.sh jru</userinput>
+WARNING: Multiple keys found for &lt;jru@FreeBSD.org&lt;; exporting all.
+WARNING: If this is not what you want, specify a key ID on the command line.
+Generating jru.key...
+Adding key to entity list...
+
+Unless you are already listed there, you should now add the following
+text to pgpkeys-developers.xml. Remember to keep the list sorted by
+last name!
+
+ &lt;sect2 xmlns="http://docbook.org/ns/docbook" xml:id="pgpkey-jru"&gt;
+ &lt;title&gt;&amp;a.jru.email;&lt;/title&gt;
+ &amp;pgpkey.jru;
+ &lt;/sect2&gt;
+
+If this is a role key or you are a core member, you should add it to
+either pgpkeys-officers.xml or pgpkeys-core.xml instead.
+
+If this is a new entry, don't forget to run the following commands
+before committing:
+
+% svn add jru.key
+% svn propset svn:keywords FreeBSD=%H jru.key
+ </screen>
+
+ <para>Use
+ <filename>doc/head/share/pgpkeys/checkkey.sh</filename> to
+ verify that keys meet minimal best-practices
+ standards.</para>
+
+ <screen>&prompt.user; <userinput>./checkkey.sh jru</userinput>
+WARNING: Multiple keys found for &lt;jru@FreeBSD.org&gt;; checking all.
+WARNING: If this is not what you want, specify a key ID on the command line.
+key E9A628D03AC59BFB: RSA, 2048 bits
+ key okay, E9A628D03AC59BFB meets minimal requirements
+ </screen>
+
+ <para>After adding and checking a key, add both updated
+ files to source control and then commit them. Entries in
+ this file are sorted by last name.</para>
+
+ <note>
+ <para>It is very important to have a current
+ <acronym>PGP</acronym>/Gnu<acronym>PG</acronym> key in
+ the repository. The key may be required for positive
+ identification of a committer. For example, the
+ &a.admins; might need it 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>
+ </step>
+
+ <step>
+ <title>Update Mentor and Mentee Information</title>
+
+ <para>Add an entry to the current committers section of
+ <filename>base/head/share/misc/committers-<replaceable>repository</replaceable>.dot</filename>
+ where <replaceable>repository</replaceable> is
+ <literal>doc</literal>, <literal>ports</literal>, or
+ <literal>src</literal>, depending on the commit privileges
+ granted.</para>
+
+ <para>Add an entry for each additional mentor/mentee
+ relationship in the bottom section.</para>
+ </step>
+
+ <step>
+ <title>Generate a <application>Kerberos</application>
+ Password</title>
+
+ <para>See <xref linkend="kerberos-ldap"/> to generate or
+ set a <application>Kerberos</application> for use with
+ other &os; services like the bug tracking database.</para>
+ </step>
+
+ <step>
+ <title>Set Up a Phabricator Account</title>
+
+ <para>A <link xlink:href="http://reviews.freebsd.org">reviews.freebsd.org</link>
+ a.k.a. "Phabricator" account allows you to submit patches for
+ review by other project members for discussion and revision prior
+ to committing. Visit <link xlink:href="http://reviews.freebsd.org/auth/register/">reviews.freebsd.org/auth/register/</link>
+ to set up a Phabricator account. If you already have a Phabricator
+ account with non-&os; email address, log into Phabricator and add
+ your @freebsd.org email address to your profile. This will require
+ you to verify your address, after which you can make your
+ @freebsd.org address your primary address. Mail<email>phabric-admin@freebsd.org</email>
+ and ask that your username be changed to your @freebsd.org address.
+ Note that when your account type is changed, you will no longer be
+ able to log in with your non-&os; password but rather will need to
+ use <application>Keberos</application>. See <xref linkend="kerberos-ldap"/>
+ for details.</para>
+ </step>
+
+ <step>
+ <title>Optional: Create a Wiki Account</title>
+
+ <para>A <link xlink:href="http://wiki.freebsd.org">wiki.freebsd.org</link>
+ account allows you to share projects and ideas that are not
+ suitable for the primary &os; documentation. wiki.freebsd.org
+ is also used for event organization such as DevSummits. Visit
+ <link xlink:href="http://wiki.freebsd.org/action/newaccount/FrontPage?action=newaccount">wiki.freebsd.org/action/newaccount/FrontPage?action=newaccount</link>
+ to create a new Wiki account.</para>
+ </step>
+
+ <step>
+ <title>Optional: Update Wiki Information</title>
+
+ <para>Some project members add entries to
+ <link xlink:href="http://wiki.freebsd.org/HowWeGotHere">How
+ We Got Here</link>,
+ <link xlink:href="http://wiki.freebsd.org/IrcNicks">Irc
+ Nicks</link>, and <link
+ xlink:href="http://wiki.freebsd.org/DogsOfFreeBSD">Dogs
+ of FreeBSD</link> pages.</para>
+ </step>
+
+ <step>
+ <title>Optional: Add Additional Personal Information</title>
+
+ <para>Some project members add entries for themselves to
+ <filename>ports/astro/xearth/files/freebsd.committers.markers</filename>
+ and
+ <filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename>
+ to show where they are located or the date of their
+ birthday.</para>
+ </step>
+
+ <step>
+ <title>Optional: Prevent Duplicate Mailings</title>
+
+ <para>Subscribers to &a.svn-src-all.name;,
+ &a.svn-ports-all.name; or &a.svn-doc-all.name; might wish
+ to unsubscribe to avoid receiving duplicate copies of
+ commit messages and followups.</para>
+ </step>
+ </procedure>
+ </sect2>
+
+ <sect2 xml:id="conventions-everyone">
+ <title>For Everyone</title>
+
+ <procedure xml:id="conventions-everyone-steps">
+ <step>
+ <para>Introduce yourself to the other developers, otherwise
+ no one will have any idea who you are or what you are
+ working on. The introduction need not be a comprehensive
+ biography, just write a paragraph or two about who you
+ are, what you plan to be working on as a developer in
+ &os;, and who will be your mentor. Email this to the
+ &a.developers; and you will be on your way!</para>
+ </step>
+
+ <step>
+ <para>Log into <systemitem>freefall.freebsd.org</systemitem>
+ and create a
+ <filename>/var/forward/<replaceable>user</replaceable></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>freefall</systemitem> may get truncated
+ without warning if space needs to be freed, 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>
+ </step>
+ </procedure>
+
+ <note>
+ <para>Those who are developers but not committers will
+ not be subscribed to the committers or developers mailing
+ lists. The subscriptions are derived from the access
+ rights.</para>
+ </note>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="ssh.guide">
+ <title>Open<acronym>SSH</acronym> Keys for &os;</title>
+
+ <para>Cryptographic keys conforming to the
+ Open<acronym>SSH</acronym> (<emphasis>Secure
+ Shell</emphasis>) standard are used by the &os; project to allow
+ access by committers to various &os; servers for source
+ commits, communication and project management.</para>
+
+ <sect2 xml:id="sshkeys-creating">
+ <title>Creating an OpenSSH Key</title>
+
+ <para>Existing OpenSSH keys can be used, but only if they
+ comply with the <acronym>ECDSA</acronym>,
+ <acronym>Ed25519</acronym> or <acronym>RSA</acronym> standards.
+ </para>
+
+ <para>For those who do not yet have an
+ Open<acronym>SSH</acronym> key, or need a new key to meet
+ &os; security requirements.</para>
+ <procedure>
+
+ <step>
+ <para>Generate a key pair using &man.ssh-keygen.1;. The key
+ pair will be saved to your <filename>$HOME/.ssh/</filename>
+ directory.</para>
+
+ <important>
+ <para>Only <acronym>ECDSA</acronym>,
+ <acronym>Ed25519</acronym> or <acronym>RSA</acronym> keys
+ are supported.</para>
+ </important>
+ </step>
+
+ <step>
+ <screen>&prompt.user; <userinput>ssh-keygen</userinput>
+Enter file in which to save the key (/home/jru/.ssh/id_rsa):
+Enter passphrase (empty for no passphrase):
+Enter same passphrase again:
+Your identification has been saved in /home/jru/.ssh/id_rsa.
+Your public key has been saved in /home/jru/.ssh/id_rsa.pub.
+The key fingerprint is:
+SHA256:E+w9UzR94MPczAeqt/IJbXYmj2/+L4wr38NofwhmDts jru@host
+The key's randomart image is:
++---[RSA 2048]----+
+| +o.o.|
+| . =.*.oo|
+| o O.* o|
+| . o * + + |
+| S + o = +|
+| ..o+* = |
+| B *o..|
+| o E.* o|
+| +o.o++|
++----[SHA256]-----+
+ </screen>
+ </step>
+
+ <step>
+ <para>Send your public key
+ (<filename>$HOME/.ssh/id_ecdsa.pub</filename>,
+ <filename>$HOME/.ssh/id_ed25519.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
+ <filename><replaceable>yourlogin</replaceable></filename>
+ in
+ <filename>/etc/ssh-keys/</filename> on
+ <systemitem>freefall</systemitem>.</para>
+ </step>
+
+ <step>
+ <para>If you do not wish to type your password in every time
+ you use &man.ssh.1;, and you use 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>
+ </procedure>
+ </sect2>
+
+ <sect2 xml:id="sshkeys-keymaster">
+ <title>OpenSSH Server-Side User Account Key Management</title>
+
+ <para>The &os; Cluster provides a self-serve service for public
+ OpenSSH key management at
+ <systemitem>keymaster.freebsd.org</systemitem>. This service
+ allows you to list, add and remove OpenSSH keys associated
+ with your @freebsd.org username.</para>
+
+ <screen>&prompt.user; <userinput>ssh keymaster.freebsd.org</userinput>
+============================================================================
+ READ ME CAREFULLY
+============================================================================
+MAKE SURE you know how to use PGP and that your key in the handbook is
+current. PGP signed email to accounts@ is your primary recovery option.
+
+You may use the following commands:
+LIST: -- show your current keys
+ ssh jru@keymaster.freebsd.org list
+
+ADD: -- Add a SINGLE public key FROM SSH STANDARD INPUT
+ ssh jru@keymaster.freebsd.org add &lt; ~/.ssh/id_ed25519.pub
+ Alternative: "ssh jru@keymaster.freebsd.org add" and cut/paste.
+(Must pass basic santiy checks. ED25519, RSA>=2048, ECDSA allowed)
+
+REMOVE: -- interactively select keys to remove from the list.
+ ssh jru@keymaster.freebsd.org remove
+
+You will receive an email copy of any changes with cc: to admin folks.
+If you need help for non-standard key configurations: accounts@freebsd.org
+
+Any changes that you make will take approximately 10 minutes to go live.
+============================================================================
+ </screen>
+ </sect2>
+
+ <sect2 xml:id="sshkeys-management">
+ <title>Local OpenSSH Key Management</title>
+
+ <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>
+
+ <para>For information on adding, changing, or removing
+ &man.ssh.1; keys, see <uri
+ xlink:href="https://wiki.freebsd.org/clusteradm/ssh-keys">this
+ article</uri>.</para>
+ </sect2>
</sect1>
<sect1 xml:id="pgpkeys">
- <title>Open<acronym>PGP</acronym> Keys for &os;</title>
+ <title><acronym>PGP</acronym>/<acronym>GnuPG</acronym> Keys for
+ &os;</title>
<para>Cryptographic keys conforming to the
- Open<acronym>PGP</acronym> (<emphasis>Pretty Good
- Privacy</emphasis>) standard are used by the &os; project to
- authenticate committers. Messages carrying important
- information like public <acronym>SSH</acronym> keys can be
- signed with the Open<acronym>PGP</acronym> key to prove that
- they are really from the committer. See
+ <acronym>PGP</acronym> (<emphasis>Pretty Good
+ Privacy</emphasis>)/<acronym>GnuPG</acronym> standard are used
+ by the &os; project to authenticate committers. Messages
+ carrying important information like new public
+ <acronym>PGP</acronym>/<acronym>GnuPG</acronym> can be signed
+ with the <acronym>PGP</acronym>/<acronym>GnuPG</acronym> key to
+ prove that they are really from the committer. See
<link xlink:href="http://www.nostarch.com/pgp_ml.htm">PGP &amp;
- GPG: Email for the Practical Paranoid by Michael Lucas</link>
+ GPG: Email for the Practical Paranoid by Michael Lucas</link>
and <link
xlink:href="http://en.wikipedia.org/wiki/Pretty_Good_Privacy"></link>
for more information.</para>
<sect2 xml:id="pgpkeys-creating">
- <title>Creating a Key</title>
+ <title>Creating a <acronym>PGP</acronym>/<acronym>GnuPG</acronym>
+ Key</title>
- <para>Existing keys can be used, but should be checked with
- <filename>doc/head/share/pgpkeys/checkkey.sh</filename>
- first.</para>
+ <para>Existing <acronym>PGP</acronym>/<acronym>GnuPG</acronym>
+ keys can be used, but should be checked with <filename>doc/head/share/pgpkeys/checkkey.sh</filename>
+ first.</para>
<para>For those who do not yet have an
- Open<acronym>PGP</acronym> key, or need a new key to meet &os;
- security requirements, here we show how to generate
- one.</para>
+ <acronym>PGP</acronym>/<acronym>GnuPG</acronym> key, or need a
+ new key to meet &os; security requirements, here we show how
+ to generate one.</para>
<procedure xml:id="pgpkeys-create-steps">
<step>
- <para>Install
- <filename role="package">security/gnupg</filename>. Enter
- these lines in <filename>~/.gnupg/gpg.conf</filename> to
- set minimum acceptable defaults:</para>
+ <para>Install <filename
+ role="package">security/gnupg</filename>. Enter these
+ lines in <filename>~/.gnupg/gpg.conf</filename> to set
+ minimum acceptable defaults:</para>
<programlisting>fixed-list-mode
keyid-format 0xlong
@@ -239,6 +833,9 @@
<step>
<para>Generate a key:</para>
+ <para>Note that you must have full control of the terminal
+ for GPG key generation to succeed. Using 'su' will fail.</para>
+
<screen>&prompt.user; <userinput>gpg --full-gen-key</userinput>
gpg (GnuPG) 2.1.8; Copyright (C) 2015 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
@@ -261,16 +858,16 @@
&lt;n&gt;m = key expires in n months
&lt;n&gt;y = key expires in n years
Key is valid for? (0) <userinput>3y</userinput> <co xml:id="co-pgp-expire"/>
-Key expires at Wed Nov 4 17:20:20 2015 MST
+Key expires at Wed Nov 4 17:20:20 2020 MST
Is this correct? (y/N) <userinput>y</userinput>
GnuPG needs to construct a user ID to identify your key.
-Real name: <userinput><replaceable>Chucky Daemon</replaceable></userinput> <co xml:id="co-pgp-realname"/>
-Email address: <userinput><replaceable>notreal@example.com</replaceable></userinput>
+Real name: <userinput><replaceable>J. Random User</replaceable></userinput> <co xml:id="co-pgp-realname"/>
+Email address: <userinput><replaceable>jru@freebsd.org</replaceable></userinput>
Comment:
You selected this USER-ID:
- "<replaceable>Chucky Daemon &lt;notreal@example.com&gt;</replaceable>"
+ "<replaceable>J. Random User &lt;jru@freebsd.org&gt;</replaceable>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? <userinput>o</userinput>
You need a Passphrase to protect your secret key.</screen>
@@ -315,7 +912,7 @@
<para>Protect your private key and passphrase. If either the
private key or passphrase may have been compromised or
disclosed, immediately notify
- <email>accounts@FreeBSD.org</email> and revoke the key.</para>
+ <email>accounts@freebsd.org</email> and revoke the key.</para>
<para>Committing the new key is shown in
<xref linkend="commit-steps"/>.</para>
@@ -334,11 +931,11 @@
<itemizedlist>
<listitem>
<para><link
- xlink:href="https://bugs.freebsd.org/bugzilla">Bugzilla</link></para>
+ xlink:href="http://bugs.freebsd.org/bugzilla">Bugzilla</link></para>
</listitem>
<listitem>
<para><link
- xlink:href="https://jenkins.freebsd.org">Jenkins</link></para>
+ xlink:href="http://jenkins.freebsd.org">Jenkins</link></para>
</listitem>
</itemizedlist>
@@ -346,7 +943,29 @@
reset a Kerberos password for an existing account using a random
password generator:</para>
- <screen>&prompt.user; <userinput>ssh kpasswd.freebsd.org</userinput></screen>
+ <screen>&prompt.user; <userinput>ssh jru@kpasswd.freebsd.org</userinput>
+FreeBSD 12.0-CURRENT (CLUSTER) #0 r306376: Tue Sep 27 19:02:08 UTC 2016
+
+Unauthorized access is strictly prohibited.
+role=kpasswd build=amd64_12@306376
+
+Hi there, jru..
+
+Sanity checking..
+Creating initial instance for jru
+===================================================================
+Generating a strong, evil random password..
+===================================================================
+Your new, ready to forget, password: Fop%o3wee3ei
+===================================================================
+You can change it with kpasswd(1) on any machine in the cluster,
+but please consider using a password manager instead. Things like
+LastPass, 1Password etc work great.
+
+Run this again to get a different random password.
+
+Connection to kpasswd.freebsd.org closed.
+ </screen>
<note>
<para>This must be done from a machine outside of the &os;.org
@@ -355,11 +974,19 @@
<para>A Kerberos password can also be set manually
by logging into <systemitem
- class="fqdomainname">freefall.FreeBSD.org</systemitem> and
+ class="fqdomainname">freefall.freebsd.org</systemitem> and
running:</para>
- <screen>&prompt.user; <userinput>kpasswd</userinput></screen>
-
+ <screen>&prompt.user; <userinput>ssh jru@freefall.freebsd.org</userinput>
+&prompt.user; <userinput>kpasswd</userinput>
+jru@FREEBSD.ORG's Password:
+kpasswd: krb5_get_init_creds: Preauthentication failed
+jru@freefall:~ % kpasswd
+jru@FREEBSD.ORG's Password:
+New password:
+Verifying - New password:
+Success : Password changed
+ </screen>
<note>
<para>Unless you have used the Kerberos-authenticated services
of the &os;.org cluster previously,
@@ -371,3673 +998,3347 @@
</sect1>
- <sect1 xml:id="committer.types">
- <title>Commit Bit Types</title>
+ <sect1 xml:id="admin">
+ <title>Administrative Links</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" 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">repo.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">repo.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">repo.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 can
+ be found in the files
+ <filename>/local/mail/<replaceable>repository-name</replaceable>-developers-archive</filename>
+ and
+ <filename>/local/mail/<replaceable>repository-name</replaceable>-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/10</literal> (10.X-STABLE),
+ <literal>stable/11</literal> (11.X-STABLE),
+ <literal>head</literal> (12-CURRENT)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
- <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>
+ <para>&man.ssh.1; is required to connect to the project hosts.
+ For more information, see <xref linkend="ssh.guide"/>.</para>
- <row>
- <entry>src</entry>
- <entry>core@</entry>
- <entry>src/, doc/ subject to appropriate review</entry>
- </row>
+ <para>Useful links:</para>
- <row>
- <entry>doc</entry>
- <entry>doceng@</entry>
- <entry>doc/, ports/, src/ documentation</entry>
- </row>
+ <itemizedlist>
+ <listitem>
+ <para><link xlink:href="&url.base;/internal/">&os;
+ Project Internal Pages</link></para>
+ </listitem>
- <row>
- <entry>ports</entry>
- <entry>portmgr@</entry>
- <entry>ports/</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ <listitem>
+ <para><link
+ xlink:href="&url.base;/internal/machines.html">&os;
+ Project Hosts</link></para>
+ </listitem>
- <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>
+ </itemizedlist>
+ </sect1>
- <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>
+ <sect1 xml:id="teams">
+ <title>FreeBSD Teams</title>
- <sect2>
- <title>Policy for Committer Activity in Other Trees</title>
+ <para>The &os; project is organized into several teams that
+ share responsibility for various aspects of the project.
+ See <link xlink:href="&url.base;/administration.html">&os;
+ Project Administrative Groups</link> for a complete
+ list of the active &os; teams.</para>
- <itemizedlist>
- <listitem>
- <para>All committers may modify
- <filename>base/head/share/misc/committers-*.dot</filename>,
- <filename>base/head/usr.bin/calendar/calendars/calendar.freebsd</filename>,
- and
- <filename>ports/head/astro/xearth/files</filename>.</para>
- </listitem>
+ <variablelist>
+ <varlistentry>
+ <term>&a.doceng;</term>
- <listitem>
- <para>doc committers may commit
- documentation changes to <filename>src</filename>
- 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>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 <application>subversion</application> 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>
- <listitem>
- <para>Any committer may make changes to any other tree
- with an "Approved by" from a non-mentored committer with
- the appropriate bit.</para>
- </listitem>
+<!--
+ <varlistentry>
+ <term>&a.bde.email;</term>
- <listitem>
- <para>Committers can aquire an additional bit by the usual
- process of finding a mentor who will propose them to core,
- doceng, or portmgr, as appropriate. 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>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>
+-->
- <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>
+ <varlistentry>
+ <term>&a.portmgr;</term>
- <sect1 xml:id="subversion-primer">
- <title>Subversion Primer</title>
+ <listitem>
+ <para>portmgr is the group responsible for maintenance
+ of the &os; Ports Collection, a repository of third
+ party software that is ported to &os;. Committers
+ interested in contributing to &os; Ports should
+ familiarize themselves with the <link
+ xlink:href="&url.books.porters-handbook;/index.html">Porter's
+ Handbook</link>.</para>
+ </listitem>
+ </varlistentry>
- <para>It is assumed that you are already familiar with the basic
- operation of Subversion. If not, start by reading the
- <link xlink:href="http://svnbook.red-bean.com/">Subversion
- Book</link>.</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>
+ <varlistentry>
+ <term>&a.re;</term>
- <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>
+ <listitem>
+ <para>The &a.re; team is responsible for setting &os;
+ 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>
- <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>
+ <varlistentry>
+ <term>&a.security-officer;</term>
- <para>Subversion can be installed from the &os; Ports
- Collection by issuing these commands:</para>
+ <listitem>
+ <para>The &a.security-officer; is responsible for overseeing
+ all security-related issues of the &os; project.</para>
+ </listitem>
+ </varlistentry>
- <screen>&prompt.root; <userinput>pkg install subversion</userinput></screen>
+ <varlistentry>
+ <term>Cluster Admin</term>
- </sect2>
+ <listitem>
+ <para>The Cluster Admin team is responsible for overseeing
+ the &os; project infrastructure.</para>
+ </listitem>
+ </varlistentry>
+<!--
+ <varlistentry>
+ <term>&a.wollman.email;</term>
- <sect2 xml:id="svn-getting-started">
- <title>Getting Started</title>
+ <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>
+-->
+ </variablelist>
+ </sect1>
- <para>There are a few ways to obtain a working copy of the tree
- from Subversion. This section will explain them.</para>
+ <sect1 xml:id="lists">
+ <title>FreeBSD Mailing Lists</title>
- <sect3 xml:id="svn-getting-started-direct-checkout">
- <title>Direct Checkout</title>
+ <para>The &os; maintains several mailing lists to facilitate
+ communication within the project.</para>
- <para>The first is to check out directly from the main
- repository. For the <literal>src</literal> tree,
- use:</para>
+ <variablelist>
+ <varlistentry>
+ <term>&a.committers;</term>
- <screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src</userinput></screen>
+ <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>
- <para>For the <literal>doc</literal> tree, use:</para>
+ <varlistentry>
+ <term>&a.developers;</term>
- <screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/doc/head /usr/doc</userinput></screen>
+ <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 expected not to
+ not publish or forward messages from the
+ &a.developers; outside the list membership without
+ permission of all of the authors. 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 for any technical discussion.
+ 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>
- <para>For the <literal>ports</literal> tree, use:</para>
+ <sect1 xml:id="rules">
+ <title>&os; Community Rules</title>
- <screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/ports/head /usr/ports</userinput></screen>
+ <para>As members of the &os; project, you form the public face of
+ the project, and how you behave has a vital impact on the public
+ perception of it.</para>
- <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><emphasis>&os; Code of Conduct</emphasis></para>
- <para>The above command will check out a
- <literal>CURRENT</literal> source tree as
- <filename><replaceable>/usr/src/</replaceable></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>repo.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@repo.freebsd.org/base/head</literal>),
- or add an entry to your <filename>~/.ssh/config</filename>
- in the form:</para>
+ <para>The &os;
+ <link xlink:href="&url.base;/internal/code-of-conduct.html">Code
+ of Conduct</link> exists to provide a consistent policy on
+ unacceptable behavior by &os; community members.</para>
- <programlisting>Host repo.freebsd.org
- User jarjar</programlisting>
+ <para>The following expands on the parts of the <emphasis>Code of
+ Conduct</emphasis> specific to committers.</para>
- <para>This is the simplest method, but it is hard to tell just
- yet how much load it will place on the repository.</para>
+ <orderedlist>
+ <listitem>
+ <para>Respect other committers.</para>
+ </listitem>
- <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>
+ <listitem>
+ <para>Respect other contributors.</para>
+ </listitem>
- <sect3 xml:id="svn-getting-started-checkout-from-a-mirror">
- <title>Checkout from a Mirror</title>
+ <listitem>
+ <para>Discuss any significant change
+ <emphasis>before</emphasis> committing.</para>
+ </listitem>
- <para>Check out a working copy from a mirror by
- substituting the mirror's <acronym>URL</acronym> for
- <literal>svn+ssh://repo.freebsd.org/base</literal>. This
- can be an official mirror or a mirror maintained by using
- <command>svnsync</command>.</para>
+ <listitem>
+ <para>Respect existing maintainers (if listed in the
+ <varname>MAINTAINER</varname> field in
+ <filename>Makefile</filename> or in
+ <filename>MAINTAINER</filename> in the top-level
+ directory).</para>
+ </listitem>
- <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>
+ <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>
- <para>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>
+ <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>
- <sect3 xml:id="svn-getting-started-base-layout">
- <title><literal>RELENG_*</literal> Branches and General
- Layout</title>
+ <listitem>
+ <para>Do not fight in public with other committers; it looks
+ bad.</para>
+ </listitem>
- <para>In <literal>svn+ssh://repo.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>
+ <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>
- <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>
+ <listitem>
+ <para>When in doubt on any procedure, ask first!</para>
+ </listitem>
- <itemizedlist>
- <listitem>
- <para><emphasis>/head/</emphasis> which corresponds to
- <literal>HEAD</literal>, also known as
- <literal>-CURRENT</literal>.</para>
- </listitem>
+ <listitem>
+ <para>Test your changes before committing them.</para>
+ </listitem>
- <listitem>
- <para><emphasis>/stable/<replaceable>n</replaceable></emphasis>
- which corresponds to
- <literal>RELENG_<replaceable>n</replaceable></literal>.</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>
- <listitem>
- <para><emphasis>/releng/<replaceable>n.n</replaceable></emphasis>
- which corresponds to
- <literal>RELENG_<replaceable>n_n</replaceable></literal>.</para>
- </listitem>
+ <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>
- <listitem>
- <para><emphasis>/release/<replaceable>n.n.n</replaceable></emphasis>
- which corresponds to
- <literal>RELENG_<replaceable>n_n_n</replaceable>_RELEASE</literal>.</para>
- </listitem>
+ <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>
- <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>
+ <sect2>
+ <title>Details</title>
- <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>
+ <orderedlist>
+ <listitem xml:id="respect">
+ <para>Respect other committers.</para>
- <sect3 xml:id="svn-getting-started-doc-layout">
- <title>&os; Documentation Project Branches and
- Layout</title>
+ <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 or by use of the
+ Phabricator service 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>surprised</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/9.3</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.</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 or other private communications to public
+ mailing lists, mail aliases, instant messaging channels or
+ social media sites. 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 third party to resolve the
+ dispute. All parties involved must then agree to be bound
+ by the decision reached by this third 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>
- <para>In <literal>svn+ssh://repo.freebsd.org/doc</literal>,
- <emphasis>doc</emphasis> refers to the repository root of
- the source tree.</para>
+ <sect2>
+ <title>Other Suggestions</title>
- <para>In general, most &os; Documentation Project work will be
- done within the <filename>head/</filename> branch of the
- documentation source tree.</para>
+ <para>When committing documentation changes, use a spell checker
+ before committing. For all XML docs, verify that the
+ formatting directives are correct by running
+ <command>make lint</command> and
+ <package>textproc/igor</package>.</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>For manual pages, run <package>sysutils/manck</package>
+ and <package>textproc/igor</package>
+ 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>Each translation set contains several subdirectories for
- the various parts of the &os; Documentation Project. A few
- noteworthy directories are:</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> .
+ 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>
- <itemizedlist>
- <listitem>
- <para><emphasis>/articles/</emphasis> contains the source
- code for articles written by various &os;
- contributors.</para>
- </listitem>
+ <sect2>
+ <title>Deprecating Features</title>
- <listitem>
- <para><emphasis>/books/</emphasis> contains the source
- code for the different books, such as the
- &os;&nbsp;Handbook.</para>
- </listitem>
+ <para>When it is necessary to remove functionality from software
+ in the base system the following guidelines should be followed
+ whenever possible:</para>
- <listitem>
- <para><emphasis>/htdocs/</emphasis> contains the source
- code for the &os;&nbsp;website.</para>
- </listitem>
- </itemizedlist>
- </sect3>
+ <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>
- <sect3 xml:id="svn-getting-started-ports-layout">
- <title>&os; Ports Tree Branches and Layout</title>
+ <sect2>
+ <title>Privacy and Confidentiality</title>
- <para>In <literal>svn+ssh://repo.freebsd.org/ports</literal>,
- <emphasis>ports</emphasis> refers to the repository root of
- the ports tree.</para>
+ <orderedlist>
+ <listitem>
+ <para>Most &os; business is done in public.</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>
+ <para>&os; is an <emphasis>open</emphasis> project. Which
+ means that not only can anyone use the source code, but
+ that most of the development process is open to public
+ scrutiny.</para>
+ </listitem>
+
+ <listitem>
+ <para>Certain sensitive matters must remain private or
+ held under embargo.</para>
+
+ <para>There unfortunately cannot be complete transparency.
+ As a &os; developer you will have a certain degree of
+ privileged access to information. Consequently you are
+ expected to respect certain requirements for
+ confidentiality. Sometimes the need for confidentiality
+ comes from external collaborators or has a specific time
+ limit. Mostly though, it is a matter of not releasing
+ private communications.</para>
+ </listitem>
+
+ <listitem>
+ <para>The Security Officer has sole control over the
+ release of security advisories.</para>
+
+ <para>Where there are security problems that affect many
+ different operating systems, &os; frequently depends on
+ early access in order to be able to prepare advisories for
+ coordinated release. Unless &os; developers can be
+ trusted to maintain security, such early access will not
+ be made available. The Security Officer is responsible
+ for controlling pre-release access to information about
+ vulnerabilities, and for timing the release of all
+ advisories. He may request help under condition of
+ confidentiality from any developer with relevant knowledge
+ in order to prepare security fixes.</para>
+ </listitem>
+
+ <listitem>
+ <para>Communications with Core are kept confidential for as
+ long as necessary.</para>
+
+ <para>Communications to core will initially be treated as
+ confidential. Eventually however, most of Core's business
+ will be summarized into the monthly or quarterly core
+ reports. Care will be taken to avoid publicising any
+ sensitive details. Records of some particularly sensitive
+ subjects may not be reported on at all and will be
+ retained only in Core's private archives.</para>
+ </listitem>
+
+ <listitem>
+ <para>Non-disclosure Agreements may be required for access
+ to certain commercially sensitive data.</para>
+
+ <para>Access to certain commercially sensitive data may
+ only be available under a Non-Disclosure Agreement. The
+ FreeBSD Foundation legal staff must be consulted before
+ any binding agreements are entered into.</para>
+ </listitem>
+
+ <listitem>
+ <para>Private communications should not be made
+ public without permission.</para>
+
+ <para>Beyond the specific requirements above there is a
+ general expectation not to publish private communications
+ between developers without the consent of all parties
+ involved. Ask permission before forwarding a message onto
+ a public mailing list, or posting it to a forum or website
+ that can be accessed by other than the original
+ correspondents.</para>
+ </listitem>
+
+ <listitem>
+ <para>Communications on project-only or restricted access
+ channels should be treated as private.</para>
+
+ <para>Similarly to personal communications, certain
+ internal communications channels, including &os; Committer
+ only mailing lists and restricted access IRC channels
+ should be considered as private communications. You need
+ permission in order to publish material from these
+ sources.</para>
+ </listitem>
+
+ <listitem>
+ <para>Core may approve publication.</para>
+
+ <para>Where it is impractical to obtain permission due to
+ the number of correspondents or where permission to
+ publish is unreasonably withheld, Core may approve release
+ of such private matters that merit more general
+ publication.</para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+ </sect1>
- <itemizedlist>
- <listitem>
- <para><emphasis>/branches/RELENG_<replaceable>n_n_n</replaceable></emphasis>
- which corresponds to
- <literal>RELENG_<replaceable>n_n_n</replaceable></literal>
- is used to merge back security updates in preparation
- for a release.</para>
- </listitem>
+ <sect1 xml:id="developer.relations">
+ <title>Developer Relations</title>
- <listitem>
- <para><emphasis>/tags/RELEASE_<replaceable>n_n_n</replaceable></emphasis>
- which corresponds to
- <literal>RELEASE_<replaceable>n_n_n</replaceable></literal>
- represents a release tag of the ports tree.</para>
- </listitem>
+ <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><replaceable>repository</replaceable>-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. An example script that lists
+ each person who has committed to
+ a given file along with the number of commits each person has
+ made can be found at on <systemitem>freefall</systemitem> at
+ <filename>~eadler/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>
- <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>
+ <note>
+ <para>Avoid sending private emails to maintainers. Other people
+ might be interested in the conversation, not just the final
+ output.</para>
+ </note>
- <sect2 xml:id="svn-daily-use">
- <title>Daily Use</title>
+ <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 &ndash; with a version control system we can
+ always change it back.</para>
- <para>This section will explain how to perform common day-to-day
- operations with Subversion.</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>
- <sect3 xml:id="svn-daily-use-help">
- <title>Help</title>
+ <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><acronym>SVN</acronym> has built in help documentation.
- It can be accessed by typing the following command:</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>
- <screen>&prompt.user; <userinput>svn help</userinput></screen>
+ <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>
- <para>Additional information can be found in the
- <link xlink:href="http://svnbook.red-bean.com/">Subversion
- Book</link>.</para>
- </sect3>
+ <sect1 xml:id="if-in-doubt">
+ <title>If in Doubt...</title>
- <sect3 xml:id="svn-daily-use-checkout">
- <title>Checkout</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>As seen earlier, to check out the &os; head
- branch:</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>
- <screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src</userinput></screen>
+ <para>For project specific or administrative questions you should
+ ask, in order:</para>
- <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>
+ <itemizedlist>
+ <listitem>
+ <para>Your mentor or former mentor.</para>
+ </listitem>
- <para>To do this, first check out the root of the
- repository:</para>
+ <listitem>
+ <para>An experienced committer on IRC, email, etc.</para>
+ </listitem>
- <screen>&prompt.user; <userinput>svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base</userinput></screen>
+ <listitem>
+ <para>Any team with a "hat", as they should give you a
+ definitive answer.</para>
+ </listitem>
- <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>
+ <listitem>
+ <para>If still not sure, ask on &a.developers;.</para>
+ </listitem>
+ </itemizedlist>
- <para>Expanding the working copy is possible. Just change the
- depth of the various subdirectories:</para>
+ <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>
- <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>
+ <sect1 xml:id="archs">
+ <title>Support for Multiple Architectures</title>
- <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>&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>
- <para>If at a later date merging to
- <literal>7-STABLE</literal> is required, expand the working
- copy:</para>
+ <sect2>
+ <title>Policy on Multiple Architectures</title>
- <screen>&prompt.user; <userinput>svn up --set-depth=infinity base/stable/7</userinput></screen>
+ <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>
- <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>
+ <blockquote>
+ <para>Our 32-bit reference platform is &arch.i386;, and our
+ 64-bit reference platform is &arch.amd64;. 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>
- <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>The &arch.i386; and &arch.amd64; 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>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>
+ <para>We will continue to re-evaluate this policy as cost and
+ availability of the 64-bit platforms change.</para>
- <note>
- <para>Decreasing the depth of a working copy is not
- possible.</para>
- </note>
- </sect3>
+ <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>
- <sect3 xml:id="svn-daily-use-anonymous-checkout">
- <title>Anonymous Checkout</title>
+ <sect2>
+ <title>Statement of General Intent</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>
+ <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>
- <screen>&prompt.user; <userinput>svn co https://svn.FreeBSD.org/base/head /usr/src</userinput></screen>
+ <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>
- <para>More details on using Subversion this way can be found
- in <link xlink:href="&url.books.handbook;/svn.html">Using
- Subversion</link>.</para>
- </sect3>
+ <sect2>
+ <title>Tier 1: Fully Supported Architectures</title>
- <sect3 xml:id="svn-daily-use-updating-the-tree">
- <title>Updating the Tree</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>To update a working copy to either the latest revision,
- or a specific revision:</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>
- <screen>&prompt.user; <userinput>svn update</userinput>
-&prompt.user; <userinput>svn update -<replaceable>r12345</replaceable></userinput></screen>
- </sect3>
+ <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>
- <sect3 xml:id="svn-daily-use-status">
- <title>Status</title>
+ <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>To view the local changes that have been made to the
- working copy:</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>
- <screen>&prompt.user; <userinput>svn status</userinput></screen>
+ <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>To show local changes and files that are out-of-date
- do:</para>
+ <para>Current Tier 1 platforms are &arch.i386; and
+ &arch.amd64;.</para>
+ </sect2>
- <screen>&prompt.user; <userinput>svn status --show-updates</userinput></screen>
- </sect3>
+ <sect2>
+ <title>Tier 2: Developmental Architectures</title>
- <sect3 xml:id="svn-daily-use-editing-and-committing">
- <title>Editing and Committing</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
+ maintainers are 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>Unlike Perforce, <acronym>SVN</acronym> does not need to
- be told in advance about file editing.</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>To commit all changes in
- the current directory and all subdirectories:</para>
+ <para>Tier 2 architectures have basic 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>
- <screen>&prompt.user; <userinput>svn commit</userinput></screen>
+ <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 relatively recent. It should be
+ integrated into the &os; documentation.</para>
- <para>To commit all changes in, for example,
- <filename><replaceable>lib/libfetch/</replaceable></filename>
- and
- <filename><replaceable>usr/bin/fetch/</replaceable></filename>
- in a single operation:</para>
+ <para>Current Tier 2 platforms are &arch.arm;, &arch.arm64;,
+ &arch.ia64; (through &os; 10),
+ &arch.pc98;, &arch.powerpc;, and &arch.sparc64;.</para>
+ </sect2>
- <screen>&prompt.user; <userinput>svn commit <replaceable>lib/libfetch</replaceable> <replaceable>usr/bin/fetch</replaceable></userinput></screen>
+ <sect2>
+ <title>Tier 3: Experimental Architectures</title>
- <para>There is also a commit wrapper for the ports tree to
- handle the properties and sanity checking your
- changes:</para>
+ <para>Tier 3 platforms are not supported by the security officer
+ and release engineering teams. At the discretion of the
+ toolchain maintainers, 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. Initial support for Tier 3 platforms should be worked on
+ in external SCM repositories.
+ The transition to &os;'s subversion should take place after
+ the platform boots multi-user on hardware; sharing via
+ subversion is needed for wider exposure; and multiple
+ developers are actively working on the platform.
+ 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>
- <screen>&prompt.user; <userinput>/usr/ports/Tools/scripts/psvn commit</userinput></screen>
- </sect3>
+ <para>Tier 3 platforms may have ports support, either integrated
+ or external, but do not require it.</para>
- <sect3 xml:id="svn-daily-use-adding-and-removing">
- <title>Adding and Removing Files</title>
+ <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>
- <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>
+ <para>Current Tier 3 platforms are &arch.mips;, and
+ &arch.riscv;.</para>
+ </sect2>
- <screen>&prompt.user; <userinput>svn add <replaceable>foo</replaceable></userinput></screen>
+ <sect2>
+ <title>Tier 4: Unsupported Architectures</title>
- <note>
- <para>Most new source files should include a
- <literal>&dollar;&os;&dollar;</literal> string near the
- start of the file. On commit, <command>svn</command> will
- expand the <literal>&dollar;&os;&dollar;</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>&dollar;&os;&dollar;</literal> string.</para>
- </note>
+ <para>Tier 4 systems are not supported in any form by the
+ project.</para>
- <para>Files can be removed with <command>svn
- remove</command>:</para>
+ <para>All systems not otherwise classified into a support tier
+ are Tier 4 systems. The &arch.ia64; platform is transitioning
+ to Tier 4 status in &os; 11.</para>
+ </sect2>
- <screen>&prompt.user; <userinput>svn remove <replaceable>foo</replaceable></userinput></screen>
+ <sect2>
+ <title>Policy on Changing the Tier of an Architecture</title>
- <para>Subversion does not require deleting the file before
- using <command>svn rm</command>, and indeed complains if
- that happens.</para>
+ <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>
- <para>It is possible to add directories with
- <command>svn add</command>:</para>
+ <sect1 xml:id="subversion-primer">
+ <title>Subversion Primer</title>
- <screen>&prompt.user; <userinput>mkdir <replaceable>bar</replaceable></userinput>
-&prompt.user; <userinput>svn add <replaceable>bar</replaceable></userinput></screen>
+ <para>It is assumed that you are already familiar with the basic
+ operation of Subversion. If not, start by reading the
+ <link xlink:href="http://svnbook.red-bean.com/">Subversion
+ Book</link>.</para>
- <para>Although <command>svn mkdir</command> makes this easier
- by combining the creation of the directory and the adding of
- it:</para>
+ <sect2 xml:id="svn-intro">
+ <title>Introduction</title>
- <screen>&prompt.user; <userinput>svn mkdir <replaceable>bar</replaceable></userinput></screen>
+ <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>Like files, directories are removed with
- <command>svn rm</command>. There is no separate command
- specifically for removing directories.</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>
- <screen>&prompt.user; <userinput>svn rm <replaceable>bar</replaceable></userinput></screen>
- </sect3>
+ <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>
- <sect3 xml:id="svn-daily-use-copying-and-moving">
- <title>Copying and Moving Files</title>
+ <para>Subversion can be installed from the &os; Ports
+ Collection by issuing these commands:</para>
- <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.root; <userinput>pkg install subversion</userinput></screen>
- <screen>&prompt.user; <userinput>svn copy <replaceable>foo.c</replaceable> <replaceable>bar.c</replaceable></userinput></screen>
+ </sect2>
- <para>The example above is equivalent to:</para>
+ <sect2 xml:id="svn-getting-started">
+ <title>Getting Started</title>
- <screen>&prompt.user; <userinput>cp foo.c bar.c</userinput>
-&prompt.user; <userinput>svn add bar.c</userinput></screen>
+ <para>There are a few ways to obtain a working copy of the tree
+ from Subversion. This section will explain them.</para>
- <para>To move and rename a file:</para>
+ <sect3 xml:id="svn-getting-started-direct-checkout">
+ <title>Direct Checkout</title>
- <screen>&prompt.user; <userinput>svn move <replaceable>foo.c</replaceable> <replaceable>bar.c</replaceable></userinput></screen>
- </sect3>
+ <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://repo.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://repo.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://repo.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><replaceable>/usr/src/</replaceable></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>repo.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@repo.freebsd.org/base/head</literal>),
+ or add an entry to your <filename>~/.ssh/config</filename>
+ in the form:</para>
- <sect3 xml:id="svn-daily-use-log-and-annotate">
- <title>Log and Annotate</title>
+ <programlisting>Host repo.freebsd.org
+ User jarjar</programlisting>
- <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>This is the simplest method, but it is hard to tell just
+ yet how much load it will place on the repository.</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>
+ <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-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>
+ <sect3 xml:id="svn-getting-started-checkout-from-a-mirror">
+ <title>Checkout from a Mirror</title>
- <screen>&prompt.user; <userinput>svn diff -c179454 .</userinput></screen>
- </sect3>
+ <para>Check out a working copy from a mirror by
+ substituting the mirror's <acronym>URL</acronym> for
+ <literal>svn+ssh://repo.freebsd.org/base</literal>. This
+ can be an official mirror or a mirror maintained by using
+ <command>svnsync</command>.</para>
- <sect3 xml:id="svn-daily-use-reverting">
- <title>Reverting</title>
+ <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>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>
+ <para>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-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>
+ <sect3 xml:id="svn-getting-started-base-layout">
+ <title><literal>RELENG_*</literal> Branches and General
+ Layout</title>
- <screen>&prompt.user; <userinput>svn resolved <replaceable>foo</replaceable></userinput></screen>
+ <para>In <literal>svn+ssh://repo.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>However, the preferred procedure is:</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>
- <screen>&prompt.user; <userinput>svn resolve --accept=working <replaceable>foo</replaceable></userinput></screen>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>/head/</emphasis> which corresponds to
+ <literal>HEAD</literal>, also known as
+ <literal>-CURRENT</literal>.</para>
+ </listitem>
- <para>The two examples are equivalent. Possible values for
- <literal>--accept</literal> are:</para>
+ <listitem>
+ <para><emphasis>/stable/<replaceable>n</replaceable></emphasis>
+ which corresponds to
+ <literal>RELENG_<replaceable>n</replaceable></literal>.</para>
+ </listitem>
- <itemizedlist>
<listitem>
- <para><literal>working</literal>: use the version in your
- working directory (which one presumes has been edited to
- resolve the conflicts).</para>
+ <para><emphasis>/releng/<replaceable>n.n</replaceable></emphasis>
+ which corresponds to
+ <literal>RELENG_<replaceable>n_n</replaceable></literal>.</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>
+ <para><emphasis>/release/<replaceable>n.n.n</replaceable></emphasis>
+ which corresponds to
+ <literal>RELENG_<replaceable>n_n_n</replaceable>_RELEASE</literal>.</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>
+ <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><literal>theirs-full</literal>: use the version that
- was retrieved when you did
- <command>svn update</command>, discarding your own
- changes.</para>
+ <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>
- </sect2>
- <sect2>
- <title>Advanced Use</title>
+ <sect3 xml:id="svn-getting-started-doc-layout">
+ <title>&os; Documentation Project Branches and
+ Layout</title>
- <sect3 xml:id="svn-advanced-use-sparse-checkouts">
- <title>Sparse Checkouts</title>
+ <para>In <literal>svn+ssh://repo.freebsd.org/doc</literal>,
+ <emphasis>doc</emphasis> refers to the repository root of
+ the source tree.</para>
- <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>In general, most &os; Documentation Project work will be
+ done within the <filename>head/</filename> branch of the
+ documentation source tree.</para>
- <para>Valid arguments to <option>--depth</option>
- are:</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><literal>empty</literal>: the directory itself
- without any of its contents.</para>
+ <para><emphasis>/articles/</emphasis> contains the source
+ code for articles written by various &os;
+ contributors.</para>
</listitem>
<listitem>
- <para><literal>files</literal>: the directory and any
- files it contains.</para>
+ <para><emphasis>/books/</emphasis> contains the source
+ code for the different books, such as the
+ &os;&nbsp;Handbook.</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>
+ <para><emphasis>/htdocs/</emphasis> contains the source
+ code for the &os;&nbsp;website.</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 <replaceable>~/freebsd</replaceable></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 <replaceable>head</replaceable></userinput></screen>
</sect3>
- <sect3 xml:id="svn-advanced-use-direct-operation">
- <title>Direct Operation</title>
+ <sect3 xml:id="svn-getting-started-ports-layout">
+ <title>&os; Ports Tree Branches and Layout</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>
+ <para>In <literal>svn+ssh://repo.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><literal>log</literal>,
- <literal>diff</literal></para>
+ <para><emphasis>/branches/RELENG_<replaceable>n_n_n</replaceable></emphasis>
+ which corresponds to
+ <literal>RELENG_<replaceable>n_n_n</replaceable></literal>
+ is used to merge back security updates in preparation
+ for a release.</para>
</listitem>
<listitem>
- <para><literal>mkdir</literal></para>
+ <para><emphasis>/tags/RELEASE_<replaceable>n_n_n</replaceable></emphasis>
+ which corresponds to
+ <literal>RELEASE_<replaceable>n_n_n</replaceable></literal>
+ represents a release tag of the ports tree.</para>
</listitem>
<listitem>
- <para><literal>remove</literal>, <literal>copy</literal>,
- <literal>rename</literal></para>
+ <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>
- <listitem>
- <para><literal>propset</literal>,
- <literal>propedit</literal>,
- <literal>propdel</literal></para>
- </listitem>
+ <sect2 xml:id="svn-daily-use">
+ <title>Daily Use</title>
- <listitem>
- <para><literal>merge</literal></para>
- </listitem>
- </itemizedlist>
+ <para>This section will explain how to perform common day-to-day
+ operations with Subversion.</para>
- <para>Branching is very fast. The following command would be
- used to branch <literal>RELENG_8</literal>:</para>
+ <sect3 xml:id="svn-daily-use-help">
+ <title>Help</title>
- <screen>&prompt.user; <userinput>svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/stable/8</userinput></screen>
+ <para><acronym>SVN</acronym> has built in help documentation.
+ It can be accessed by typing the following command:</para>
- <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 help</userinput></screen>
- <screen>&prompt.user; <userinput>svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base</userinput>
-&prompt.user; <userinput>cd base</userinput>
-&prompt.user; <userinput>svn update --set-depth=infinity head</userinput>
-&prompt.user; <userinput>svn copy head stable/8</userinput>
-&prompt.user; <userinput>svn commit stable/8</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-advanced-use-merging">
- <title>Merging with <acronym>SVN</acronym></title>
+ <sect3 xml:id="svn-daily-use-checkout">
+ <title>Checkout</title>
- <para>This section deals with merging code from one branch to
- another (typically, from head to a stable branch).</para>
+ <para>As seen earlier, to check out the &os; head
+ branch:</para>
- <note>
- <para>In all examples below, <literal>&dollar;FSVN</literal>
- refers to the location of the &os; Subversion repository,
- <literal>svn+ssh://repo.freebsd.org/base/</literal>.</para>
- </note>
+ <screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src</userinput></screen>
- <sect4>
- <title>About Merge Tracking</title>
+ <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>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>To do this, first check out the root of the
+ repository:</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>
+ <screen>&prompt.user; <userinput>svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base</userinput></screen>
- <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>
+ <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>
- <listitem>
- <para>Information about the current merge will
- <emphasis>not</emphasis> be propagated back up that
- ancestor.</para>
- </listitem>
+ <para>Expanding the working copy is possible. Just change the
+ depth of the various subdirectories:</para>
- <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>
+ <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>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>
+ <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>
- <sect4 xml:id="merge-source">
- <title>Selecting the Source and Target Branch
- When Merging</title>
+ <para>If at a later date merging to
+ <literal>7-STABLE</literal> is required, expand the working
+ copy:</para>
- <para>Merging to <literal>stable/</literal> branches should
- originate from <literal>head/</literal>. For
- example:</para>
+ <screen>&prompt.user; <userinput>svn up --set-depth=infinity base/stable/7</userinput></screen>
- <screen>&prompt.user; svn merge -c <replaceable>r123456</replaceable> ^/head/ stable/<replaceable>11</replaceable>
-&prompt.user; svn commit stable/<replaceable>11</replaceable></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>
- <note>
- <para>Note the sections below which outline changes to
- the target location of the <literal>stable/</literal>
- branch starting with
- <literal>stable/10</literal>.</para>
- </note>
+ <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>Merges to <literal>releng/</literal> branches should
- always originate from the corresponding
- <literal>stable/</literal> branch. For example:</para>
+ <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>
- <screen>&prompt.user; svn merge -c <replaceable>r123456</replaceable> ^/stable/<replaceable>11</replaceable> releng/<replaceable>11.0</replaceable>
-&prompt.user; svn commit releng/<replaceable>11.0</replaceable></screen>
+ <note>
+ <para>Decreasing the depth of a working copy is not
+ possible.</para>
+ </note>
+ </sect3>
- <note>
- <para>Committers are only permitted to commit to the
- <literal>releng/</literal> branches during a release
- cycle after receiving approval from the Release
- Engineering Team, after which only the Security Officer
- may commit to a <literal>releng/</literal> branch for
- a Security Advisory or Errata Notice.</para>
- </note>
- </sect4>
+ <sect3 xml:id="svn-daily-use-anonymous-checkout">
+ <title>Anonymous Checkout</title>
- <sect4 xml:id="merge">
- <title>Selecting the Source and Target for
- <literal>stable/10</literal> and Newer</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>
- <para>Starting with the <literal>stable/10</literal>
- branch, all merges should be
- merged to and committed from the root of the
- branch. All merges should look like:</para>
+ <screen>&prompt.user; <userinput>svn co http://svn.freebsd.org/base/head /usr/src</userinput></screen>
- <screen>&prompt.user; svn merge -c <replaceable>r123456</replaceable> ^/head/ <replaceable>checkout</replaceable>
-&prompt.user; svn commit <replaceable>checkout</replaceable></screen>
+ <para>More details on using Subversion this way can be found
+ in <link xlink:href="&url.books.handbook;/svn.html">Using
+ Subversion</link>.</para>
+ </sect3>
- <para>Note that <replaceable>checkout</replaceable> should
- be a complete checkout of the branch to which the merge
- occurs.</para>
- </sect4>
+ <sect3 xml:id="svn-daily-use-updating-the-tree">
+ <title>Updating the Tree</title>
- <sect4 xml:id="oldmerge">
- <title>Selecting the Source and Target for
- <literal>stable/9</literal> and Older</title>
+ <para>To update a working copy to either the latest revision,
+ or a specific revision:</para>
- <para>For <literal>stable/9</literal> and earlier,
- a different strategy was used, distributing mergeinfo
- around the tree so that merges could be performed without
- a complete checkout. This procedure proved extremely
- error-prone, with the convenience of partial checkouts for
- merges significantly outweighed by the complexity of
- picking mergeinfo targets. The below describes this
- now-obsoleted procedure, which should be used
- <emphasis>only for merges prior to
- <literal>stable/10</literal></emphasis>.</para>
+ <screen>&prompt.user; <userinput>svn update</userinput>
+&prompt.user; <userinput>svn update -<replaceable>r12345</replaceable></userinput></screen>
+ </sect3>
- <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>
+ <sect3 xml:id="svn-daily-use-status">
+ <title>Status</title>
- <para>The rules for selecting the merge target (the
- directory that you will merge the changes to) can be
- summarized as follows:</para>
+ <para>To view the local changes that have been made to the
+ working copy:</para>
- <orderedlist>
- <listitem>
- <para>Never merge directly to a file.</para>
- </listitem>
+ <screen>&prompt.user; <userinput>svn status</userinput></screen>
- <listitem>
- <para>Never, ever merge directly to a file.</para>
- </listitem>
+ <para>To show local changes and files that are out-of-date
+ do:</para>
- <listitem>
- <para><emphasis>Never, ever, ever</emphasis> merge
- directly to a file.</para>
- </listitem>
+ <screen>&prompt.user; <userinput>svn status --show-updates</userinput></screen>
+ </sect3>
- <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>
+ <sect3 xml:id="svn-daily-use-editing-and-committing">
+ <title>Editing and Committing</title>
- <listitem>
- <para>Changes to code under <filename>etc/</filename>
- should be merged at <filename>etc/</filename>, not
- below it.</para>
- </listitem>
+ <para>Unlike Perforce, <acronym>SVN</acronym> does not need to
+ be told in advance about file editing.</para>
- <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>
+ <para>To commit all changes in
+ the current directory and all subdirectories:</para>
- <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>
+ <screen>&prompt.user; <userinput>svn commit</userinput></screen>
- <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>
+ <para>To commit all changes in, for example,
+ <filename><replaceable>lib/libfetch/</replaceable></filename>
+ and
+ <filename><replaceable>usr/bin/fetch/</replaceable></filename>
+ in a single operation:</para>
- <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>
+ <screen>&prompt.user; <userinput>svn commit <replaceable>lib/libfetch</replaceable> <replaceable>usr/bin/fetch</replaceable></userinput></screen>
- <listitem>
- <para>Changes to manual pages should be merged to
- <filename>share/man/man<replaceable>N</replaceable>/</filename>,
- for the appropriate value of
- <literal>N</literal>.</para>
- </listitem>
+ <para>There is also a commit wrapper for the ports tree to
+ handle the properties and sanity checking your
+ changes:</para>
- <listitem>
- <para>Other changes to <filename>share/</filename>
- should be merged to the appropriate subdirectory and
- not to <filename>share/</filename> directly.</para>
- </listitem>
+ <screen>&prompt.user; <userinput>/usr/ports/Tools/scripts/psvn commit</userinput></screen>
+ </sect3>
- <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>
+ <sect3 xml:id="svn-daily-use-adding-and-removing">
+ <title>Adding and Removing Files</title>
- <listitem>
- <para>When in doubt, ask.</para>
- </listitem>
- </orderedlist>
+ <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>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>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>
- <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>
+ <screen>&prompt.user; <userinput>svn add <replaceable>foo</replaceable></userinput></screen>
- <sect4>
- <title>Preparing the Merge Target</title>
+ <note>
+ <para>Most new source files should include a
+ <literal>&dollar;&os;&dollar;</literal> string near the
+ start of the file. On commit, <command>svn</command> will
+ expand the <literal>&dollar;&os;&dollar;</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>&dollar;&os;&dollar;</literal> string.</para>
+ </note>
- <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>
+ <para>Files can be removed with <command>svn
+ remove</command>:</para>
- <screen>&prompt.user; <userinput>cd stable/7</userinput>
-&prompt.user; <userinput>svn up --set-depth=infinity</userinput></screen>
+ <screen>&prompt.user; <userinput>svn remove <replaceable>foo</replaceable></userinput></screen>
- <para>The target directory must also be up-to-date and must
- not contain any uncommitted changes or stray files.</para>
- </sect4>
+ <para>Subversion does not require deleting the file before
+ using <command>svn rm</command>, and indeed complains if
+ that happens.</para>
- <sect4>
- <title>Identifying Revisions</title>
+ <para>It is possible to add directories with
+ <command>svn add</command>:</para>
- <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>mkdir <replaceable>bar</replaceable></userinput>
+&prompt.user; <userinput>svn add <replaceable>bar</replaceable></userinput></screen>
- <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>Although <command>svn mkdir</command> makes this easier
+ by combining the creation of the directory and the adding of
+ it:</para>
- <para>If the target does not have complete mergeinfo, check
- the log for the merge source.</para>
- </sect4>
+ <screen>&prompt.user; <userinput>svn mkdir <replaceable>bar</replaceable></userinput></screen>
- <sect4>
- <title>Merging</title>
+ <para>Like files, directories are removed with
+ <command>svn rm</command>. There is no separate command
+ specifically for removing directories.</para>
- <para>Now, let us start merging!</para>
+ <screen>&prompt.user; <userinput>svn rm <replaceable>bar</replaceable></userinput></screen>
+ </sect3>
- <sect5>
- <title>The Principles</title>
+ <sect3 xml:id="svn-daily-use-copying-and-moving">
+ <title>Copying and Moving Files</title>
- <para>Say you would like to merge:</para>
+ <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>
- <itemizedlist>
- <listitem>
- <para>revision <literal>&dollar;R</literal></para>
- </listitem>
+ <screen>&prompt.user; <userinput>svn copy <replaceable>foo.c</replaceable> <replaceable>bar.c</replaceable></userinput></screen>
- <listitem>
- <para>in directory &dollar;target in stable branch
- &dollar;B</para>
- </listitem>
+ <para>The example above is equivalent to:</para>
- <listitem>
- <para>from directory &dollar;source in head</para>
- </listitem>
+ <screen>&prompt.user; <userinput>cp foo.c bar.c</userinput>
+&prompt.user; <userinput>svn add bar.c</userinput></screen>
- <listitem>
- <para>&dollar;FSVN is
- <literal>svn+ssh://repo.freebsd.org/base</literal></para>
- </listitem>
- </itemizedlist>
+ <para>To move and rename a file:</para>
- <para>Assuming that revisions &dollar;P and &dollar;Q have
- already been merged, and that the current directory is
- an up-to-date working copy of stable/&dollar;B, the
- existing mergeinfo looks like this:</para>
+ <screen>&prompt.user; <userinput>svn move <replaceable>foo.c</replaceable> <replaceable>bar.c</replaceable></userinput></screen>
+ </sect3>
- <screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R $target</userinput>
-$target - /head/$source:$P,$Q</screen>
+ <sect3 xml:id="svn-daily-use-log-and-annotate">
+ <title>Log and Annotate</title>
- <para>Merging is done like so:</para>
+ <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>
- <screen>&prompt.user; <userinput>svn merge -c$R $FSVN/head/$source $target</userinput></screen>
+ <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>
- <para>Checking the results of this is possible with
- <command>svn diff</command>.</para>
+ <sect3 xml:id="svn-daily-use-diffs">
+ <title>Diffs</title>
- <para>The svn:mergeinfo now looks like:</para>
+ <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>
- <screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R $target</userinput>
-$target - head/$source:$P,$Q,$R</screen>
+ <para><command>svn diff</command> can show the changes between
+ two revisions of the same file:</para>
- <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>
+ <screen>&prompt.user; <userinput>svn diff -r179453:179454 ROADMAP.txt</userinput></screen>
- <sect5>
- <title>Practical Example</title>
+ <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>
- <para>As a practical example, consider the following
- scenario. The changes to <filename>netmap.4</filename>
- in r238987 are to be merged from CURRENT to 9-STABLE.
- The file resides in
- <filename>head/share/man/man4</filename>. 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>
+ <screen>&prompt.user; <userinput>svn diff -c179454 .</userinput></screen>
+ </sect3>
- <para>The first step is to inspect the existing
- mergeinfo.</para>
+ <sect3 xml:id="svn-daily-use-reverting">
+ <title>Reverting</title>
- <screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R stable/9/share/man/man4</userinput></screen>
+ <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>
- <para>Take a quick note of how it looks before moving on
- to the next step; doing the actual merge:</para>
+ <sect3 xml:id="svn-daily-use-conflicts">
+ <title>Conflicts</title>
- <screen>&prompt.user; <userinput>svn merge -c r238987 svn+ssh://repo.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>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>
- <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 resolved <replaceable>foo</replaceable></userinput></screen>
- <screen>&prompt.user; <userinput>svn commit stable/9/share/man/man4</userinput></screen>
- </sect5>
+ <para>However, the preferred procedure is:</para>
- <sect5>
- <title>Merging into the Kernel
- (<filename>sys/</filename>)</title>
+ <screen>&prompt.user; <userinput>svn resolve --accept=working <replaceable>foo</replaceable></userinput></screen>
- <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>The two examples are equivalent. Possible values for
+ <literal>--accept</literal> are:</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>
+ <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>
- <sect4>
- <title>Precautions Before Committing</title>
+ <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>
- <para>As always, build world (or appropriate parts of
- it).</para>
+ <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>
- <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>
+ <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>
- <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>
+ <sect2>
+ <title>Advanced Use</title>
- <para>If something looks fishy, ask for help.</para>
- </sect4>
+ <sect3 xml:id="svn-advanced-use-sparse-checkouts">
+ <title>Sparse Checkouts</title>
- <sect4>
- <title>Committing</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>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>
+ <para>Valid arguments to <option>--depth</option>
+ are:</para>
- <sect3 xml:id="svn-advanced-use-vendor-imports">
- <title>Vendor Imports with <acronym>SVN</acronym></title>
+ <itemizedlist>
+ <listitem>
+ <para><literal>empty</literal>: the directory itself
+ without any of its contents.</para>
+ </listitem>
- <important>
- <para>Please read this entire section before starting a
- vendor import.</para>
- </important>
+ <listitem>
+ <para><literal>files</literal>: the directory and any
+ files it contains.</para>
+ </listitem>
- <note>
- <para>Patches to vendor code fall into two
- categories:</para>
+ <listitem>
+ <para><literal>immediates</literal>: the directory and any
+ files and directories it contains, but none of the
+ subdirectories' contents.</para>
+ </listitem>
- <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><literal>infinity</literal>: anything.</para>
+ </listitem>
+ </itemizedlist>
- <listitem>
- <para>&os; patches: these are patches that modify the
- vendor code to address &os;-specific issues.</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>The nature of a patch dictates where it should be
- committed:</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>
- <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>
+ <screen>&prompt.user; <userinput>cd <replaceable>~/freebsd</replaceable></userinput>
+&prompt.user; <userinput>svn update --set-depth=immediates .</userinput></screen>
- <listitem>
- <para>&os; patches should be committed directly to
- head.</para>
- </listitem>
- </itemizedlist>
- </note>
+ <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>
- <sect4>
- <title>Preparing the Tree</title>
+ <screen>&prompt.user; <userinput>svn update --set-depth=infinity <replaceable>head</replaceable></userinput></screen>
+ </sect3>
- <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>
+ <sect3 xml:id="svn-advanced-use-direct-operation">
+ <title>Direct Operation</title>
- <sect5>
- <title>Flattening</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>
- <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>
+ <itemizedlist>
+ <listitem>
+ <para><literal>log</literal>,
+ <literal>diff</literal></para>
+ </listitem>
- <para>To flatten the <literal>pf</literal> tree:</para>
+ <listitem>
+ <para><literal>mkdir</literal></para>
+ </listitem>
- <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/dist/contrib/pf</replaceable></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>
+ <listitem>
+ <para><literal>remove</literal>, <literal>copy</literal>,
+ <literal>rename</literal></para>
+ </listitem>
- <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>
+ <listitem>
+ <para><literal>propset</literal>,
+ <literal>propedit</literal>,
+ <literal>propdel</literal></para>
+ </listitem>
- <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>
+ <listitem>
+ <para><literal>merge</literal></para>
+ </listitem>
+ </itemizedlist>
- <sect5>
- <title>Cleaning Up</title>
+ <para>Branching is very fast. The following command would be
+ used to branch <literal>RELENG_8</literal>:</para>
- <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 copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/stable/8</userinput></screen>
- <screen>&prompt.user; <userinput>svn propdel svn:keywords -R .</userinput>
-&prompt.user; <userinput>svn commit</userinput></screen>
- </sect5>
+ <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>
- <sect5>
- <title>Bootstrapping Merge History</title>
+ <screen>&prompt.user; <userinput>svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base</userinput>
+&prompt.user; <userinput>cd base</userinput>
+&prompt.user; <userinput>svn update --set-depth=infinity head</userinput>
+&prompt.user; <userinput>svn copy head stable/8</userinput>
+&prompt.user; <userinput>svn commit stable/8</userinput></screen>
+ </sect3>
- <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>
+ <sect3 xml:id="svn-advanced-use-merging">
+ <title>Merging with <acronym>SVN</acronym></title>
- <screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput>
-&prompt.user; <userinput>svn merge --record-only svn+ssh://repo.freebsd.org/base/<replaceable>vendor/pf/dist@180876</replaceable> .</userinput>
-&prompt.user; <userinput>svn commit</userinput></screen>
- </sect5>
- </sect4>
+ <para>This section deals with merging code from one branch to
+ another (typically, from head to a stable branch).</para>
- <sect4>
- <title>Importing New Sources</title>
+ <note>
+ <para>In all examples below, <literal>&dollar;FSVN</literal>
+ refers to the location of the &os; Subversion repository,
+ <literal>svn+ssh://repo.freebsd.org/base/</literal>.</para>
+ </note>
- <para>With two commits&mdash;one for the import itself and
- one for the tag&mdash;this step can optionally be repeated
- for every upstream release between the last import and the
- current import.</para>
+ <sect4>
+ <title>About Merge Tracking</title>
- <sect5>
- <title>Preparing the Vendor Sources</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>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>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>
- <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>
+ <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>
- <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/dist</replaceable></userinput>
-&prompt.user; <userinput>svn list -R | grep -v '/$' | sort &gt;../old</userinput>
-&prompt.user; <userinput>cd <replaceable>../pf-4.3</replaceable></userinput>
-&prompt.user; <userinput>find . -type f | cut -c 3- | sort &gt;../new</userinput></screen>
+ <listitem>
+ <para>Information about the current merge will
+ <emphasis>not</emphasis> be propagated back up that
+ ancestor.</para>
+ </listitem>
- <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>
+ <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>
- <sect5>
- <title>Importing into the Vendor Tree</title>
+ <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>
- <para>Now, the sources must be copied into
- <filename><replaceable>dist</replaceable></filename> and
- the <command>svn add</command> and
- <command>svn rm</command> commands should be used as
- needed:</para>
+ <sect4 xml:id="merge-source">
+ <title>Selecting the Source and Target Branch
+ When Merging</title>
- <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/pf-4.3</replaceable></userinput>
-&prompt.user; <userinput>tar cf - . | tar xf - -C ../dist</userinput>
-&prompt.user; <userinput>cd <replaceable>../dist</replaceable></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>Merging to <literal>stable/</literal> branches should
+ originate from <literal>head/</literal>. For
+ example:</para>
- <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>
+ <screen>&prompt.user; svn merge -c <replaceable>r123456</replaceable> ^/head/ stable/<replaceable>11</replaceable>
+&prompt.user; svn commit stable/<replaceable>11</replaceable></screen>
- <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>
+ <note>
+ <para>Note the sections below which outline changes to
+ the target location of the <literal>stable/</literal>
+ branch starting with
+ <literal>stable/10</literal>.</para>
+ </note>
- <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>
+ <para>Merges to <literal>releng/</literal> branches should
+ always originate from the corresponding
+ <literal>stable/</literal> branch. For example:</para>
- <sect5>
- <title>Tagging</title>
+ <screen>&prompt.user; svn merge -c <replaceable>r123456</replaceable> ^/stable/<replaceable>11</replaceable> releng/<replaceable>11.0</replaceable>
+&prompt.user; svn commit releng/<replaceable>11.0</replaceable></screen>
- <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>
+ <note>
+ <para>Committers are only permitted to commit to the
+ <literal>releng/</literal> branches during a release
+ cycle after receiving approval from the Release
+ Engineering Team, after which only the Security Officer
+ may commit to a <literal>releng/</literal> branch for
+ a Security Advisory or Errata Notice.</para>
+ </note>
+ </sect4>
- <screen>&prompt.user; <userinput>svn cp svn+ssh://repo.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> svn+ssh://repo.freebsd.org/base/<replaceable>vendor/pf/4.3</replaceable></userinput></screen>
+ <sect4 xml:id="merge">
+ <title>Selecting the Source and Target for
+ <literal>stable/10</literal> and Newer</title>
- <para>Once that is complete, <command>svn up</command> the
- working copy of
- <filename><replaceable>vendor/pf</replaceable></filename>
- to get the new tag, although this is rarely
- needed.</para>
+ <para>Starting with the <literal>stable/10</literal>
+ branch, all merges should be
+ merged to and committed from the root of the
+ branch. All merges should look like:</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; svn merge -c <replaceable>r123456</replaceable> ^/head/ <replaceable>checkout</replaceable>
+&prompt.user; svn commit <replaceable>checkout</replaceable></screen>
- <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf</replaceable></userinput>
-&prompt.user; <userinput>svn cp dist 4.3</userinput>
-&prompt.user; <userinput>svn propdel svn:mergeinfo -R 4.3</userinput></screen>
- </sect5>
+ <para>Note that <replaceable>checkout</replaceable> should
+ be a complete checkout of the branch to which the merge
+ occurs.</para>
</sect4>
- <sect4>
- <title>Merging to Head</title>
+ <sect4 xml:id="oldmerge">
+ <title>Selecting the Source and Target for
+ <literal>stable/9</literal> and Older</title>
- <screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput>
-&prompt.user; <userinput>svn up</userinput>
-&prompt.user; <userinput>svn merge --accept=postpone svn+ssh://repo.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> .</userinput></screen>
+ <para>For <literal>stable/9</literal> and earlier,
+ a different strategy was used, distributing mergeinfo
+ around the tree so that merges could be performed without
+ a complete checkout. This procedure proved extremely
+ error-prone, with the convenience of partial checkouts for
+ merges significantly outweighed by the complexity of
+ picking mergeinfo targets. The below describes this
+ now-obsoleted procedure, which should be used
+ <emphasis>only for merges prior to
+ <literal>stable/10</literal></emphasis>.</para>
- <para>The <literal>--accept=postpone</literal> tells
- Subversion that it should not complain because merge
- conflicts will be taken care of manually.</para>
+ <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>
- <tip xml:id="svn-advanced-use-vendor-imports-pre-svn">
- <para>The <command>cvs2svn</command> changeover occurred
- on June 3, 2008. When performing vendor merges for
- packages which were already present and converted by the
- <command>cvs2svn</command> process, the command used to
- merge
- <filename>/vendor/<replaceable>package_name</replaceable>/dist</filename>
- to
- <filename>/head/<replaceable>package_location</replaceable></filename>
- (for example,
- <filename>head/contrib/sendmail</filename>) must use
- <option>-c <replaceable>REV</replaceable></option> to
- indicate the revision to merge from the
- <filename>/vendor</filename> tree. For example:</para>
+ <para>The rules for selecting the merge target (the
+ directory that you will merge the changes to) can be
+ summarized as follows:</para>
- <screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/base/head/contrib/<replaceable>sendmail</replaceable></userinput>
-&prompt.user; <userinput>cd sendmail</userinput>
-&prompt.user; <userinput>svn merge -c r<replaceable>261190</replaceable> ^/vendor/<replaceable>sendmail/dist</replaceable> .</userinput></screen>
+ <orderedlist>
+ <listitem>
+ <para>Never merge directly to a file.</para>
+ </listitem>
- <para><literal>^</literal> is an alias for the
- repository path.</para>
- </tip>
+ <listitem>
+ <para>Never, ever merge directly to a file.</para>
+ </listitem>
- <note>
- <para>If using the <application>Zsh</application> shell,
- the <literal>^</literal> must be escaped with
- <literal>\</literal>. This means
- <literal>^/head</literal> should be
- <literal>\^/head</literal>.</para>
- </note>
+ <listitem>
+ <para><emphasis>Never, ever, ever</emphasis> merge
+ directly to a file.</para>
+ </listitem>
- <para>It is necessary to resolve any merge conflicts.</para>
+ <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>
- <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>
+ <listitem>
+ <para>Changes to code under <filename>etc/</filename>
+ should be merged at <filename>etc/</filename>, not
+ below it.</para>
+ </listitem>
- <screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=svn+ssh://repo.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> --new=.</userinput></screen>
+ <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>
- <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>
+ <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>
- <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>
+ <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>
- <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>
+ <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>
- <sect4>
- <title>Committing the Vendor Import</title>
+ <listitem>
+ <para>Changes to manual pages should be merged to
+ <filename>share/man/man<replaceable>N</replaceable>/</filename>,
+ for the appropriate value of
+ <literal>N</literal>.</para>
+ </listitem>
- <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>
+ <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>From Scratch</title>
+ <title>Preparing the Merge Target</title>
- <sect5>
- <title>Importing into the Vendor Tree</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>
- <para>This section is an example of importing and tagging
- <application>byacc</application> into
- <filename>head</filename>.</para>
+ <screen>&prompt.user; <userinput>cd stable/7</userinput>
+&prompt.user; <userinput>svn up --set-depth=infinity</userinput></screen>
- <para>First, prepare the directory in
- <filename>vendor</filename>:</para>
+ <para>The target directory must also be up-to-date and must
+ not contain any uncommitted changes or stray files.</para>
+ </sect4>
- <screen>&prompt.user; <userinput>svn co --depth immediates <replaceable>$FSVN/vendor</replaceable></userinput>
-&prompt.user; <userinput>cd <replaceable>vendor</replaceable></userinput>
-&prompt.user; <userinput>svn mkdir <replaceable>byacc</replaceable></userinput>
-&prompt.user; <userinput>svn mkdir <replaceable>byacc/dist</replaceable></userinput></screen>
+ <sect4>
+ <title>Identifying Revisions</title>
- <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>
+ <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>svn cp -m <replaceable>"Tag byacc 20120115"</replaceable> <replaceable>$FSVN/vendor/byacc/dist</replaceable> <replaceable>$FSVN/vendor/byacc/20120115</replaceable></userinput></screen>
- </sect5>
+ <screen>&prompt.user; <userinput>cd stable/6/contrib/openpam</userinput>
+&prompt.user; <userinput>svn mergeinfo --show-revs=eligible $FSVN/head/contrib/openpam</userinput></screen>
- <sect5>
- <title>Merging to <literal>head</literal></title>
+ <para>If the target does not have complete mergeinfo, check
+ the log for the merge source.</para>
+ </sect4>
- <para>Due to this being a new file, copy it for the
- merge:</para>
+ <sect4>
+ <title>Merging</title>
- <screen>&prompt.user; <userinput>svn cp -m <replaceable>"Import byacc to contrib"</replaceable> <replaceable>$FSVN/vendor/byacc/dist</replaceable> <replaceable>$FSVN/head/contrib/byacc</replaceable></userinput></screen>
+ <para>Now, let us start merging!</para>
- <para>Working normally on newly imported sources is still
- possible.</para>
- </sect5>
- </sect4>
- </sect3>
+ <sect5>
+ <title>The Principles</title>
- <sect3 xml:id="svn-advanced-use-reverting-a-commit">
- <title>Reverting a Commit</title>
+ <para>Say you would like to merge:</para>
- <para>Reverting a commit to a previous version is fairly
- easy:</para>
+ <itemizedlist>
+ <listitem>
+ <para>revision <literal>&dollar;R</literal></para>
+ </listitem>
- <screen>&prompt.user; <userinput>svn merge -r179454:179453 ROADMAP.txt</userinput>
-&prompt.user; <userinput>svn commit</userinput></screen>
+ <listitem>
+ <para>in directory &dollar;target in stable branch
+ &dollar;B</para>
+ </listitem>
- <para>Change number syntax, with negative meaning a reverse
- change, can also be used:</para>
+ <listitem>
+ <para>from directory &dollar;source in head</para>
+ </listitem>
- <screen>&prompt.user; <userinput>svn merge -c -179454 ROADMAP.txt</userinput>
-&prompt.user; <userinput>svn commit</userinput></screen>
+ <listitem>
+ <para>&dollar;FSVN is
+ <literal>svn+ssh://repo.freebsd.org/base</literal></para>
+ </listitem>
+ </itemizedlist>
- <para>This can also be done directly in the repository:</para>
+ <para>Assuming that revisions &dollar;P and &dollar;Q have
+ already been merged, and that the current directory is
+ an up-to-date working copy of stable/&dollar;B, the
+ existing mergeinfo looks like this:</para>
- <screen>&prompt.user; <userinput>svn merge -r179454:179453 svn+ssh://repo.freebsd.org/base/ROADMAP.txt</userinput></screen>
+ <screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R $target</userinput>
+$target - /head/$source:$P,$Q</screen>
- <note>
- <para>It is important to ensure that the mergeinfo
- is correct when reverting a file in order to permit
- <command>svn mergeinfo --show-revs=eligible</command> to work as
- expected.</para>
- </note>
+ <para>Merging is done like so:</para>
- <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 merge -c$R $FSVN/head/$source $target</userinput></screen>
- <screen>&prompt.user; <userinput>svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454</userinput>
-&prompt.user; <userinput>svn commit</userinput></screen>
+ <para>Checking the results of this is possible with
+ <command>svn diff</command>.</para>
- <para>or, equally:</para>
+ <para>The svn:mergeinfo now looks like:</para>
- <screen>&prompt.user; <userinput>svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 svn+ssh://repo.freebsd.org/base</userinput></screen>
+ <screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R $target</userinput>
+$target - head/$source:$P,$Q,$R</screen>
- <para>Do <emphasis>not</emphasis> simply recreate the file
- manually and <command>svn add</command> it&mdash;this will
- cause history to be lost.</para>
- </sect3>
+ <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>
- <sect3 xml:id="svn-advanced-use-fixing-mistakes">
- <title>Fixing Mistakes</title>
+ <sect5>
+ <title>Practical Example</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>As a practical example, consider the following
+ scenario. The changes to <filename>netmap.4</filename>
+ in r238987 are to be merged from CURRENT to 9-STABLE.
+ The file resides in
+ <filename>head/share/man/man4</filename>. 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>Mistakes will happen but,
- they can generally be fixed without
- disruption.</para>
+ <para>The first step is to inspect the existing
+ mergeinfo.</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>
+ <screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R stable/9/share/man/man4</userinput></screen>
- <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>
+ <para>Take a quick note of how it looks before moving on
+ to the next step; doing the actual merge:</para>
- <sect3 xml:id="svn-advanced-use-setting-up-svnsync">
- <title>Setting up a <application>svnsync</application>
- Mirror</title>
+ <screen>&prompt.user; <userinput>svn merge -c r238987 svn+ssh://repo.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>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>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>
- <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>svn commit stable/9/share/man/man4</userinput></screen>
+ </sect5>
- <screen>&prompt.user; <userinput>rsync -va --partial --progress freefall:/home/peter/svnmirror-base-r179637.tbz2 .</userinput></screen>
+ <sect5>
+ <title>Merging into the Kernel
+ (<filename>sys/</filename>)</title>
- <screen>&prompt.user; <userinput>rsync -va --partial --progress rsync://repoman.freebsd.org:50873/svnseed/svnmirror-base-r215629.tar.xz .</userinput></screen>
+ <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>
- <screen>&prompt.user; <userinput>fetch ftp://ftp.freebsd.org/pub/FreeBSD/development/subversion/svnmirror-base-r221445.tar.xz</userinput></screen>
+ <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>
- <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>
+ <sect4>
+ <title>Precautions Before Committing</title>
- <screen>&prompt.user; <userinput>svnsync sync file:///home/svnmirror/base</userinput></screen>
+ <para>As always, build world (or appropriate parts of
+ it).</para>
- <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>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>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>
+ <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>
- <screen>&prompt.user; <userinput>svn proplist -v --revprop -r 0 file:///home/svnmirror/base</userinput></screen>
+ <para>If something looks fishy, ask for help.</para>
+ </sect4>
- <para>Use <literal>propset</literal> to change things.</para>
- </sect3>
+ <sect4>
+ <title>Committing</title>
- <sect3 xml:id="svn-advanced-use-committing-high-ascii-data">
- <title>Committing High-<acronym>ASCII</acronym> Data</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>
- <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>
+ <sect3 xml:id="svn-advanced-use-vendor-imports">
+ <title>Vendor Imports with <acronym>SVN</acronym></title>
- <screen>&prompt.user; <userinput>svn propset fbsd:notbinary yes foo.data</userinput></screen>
- </sect3>
+ <important>
+ <para>Please read this entire section before starting a
+ vendor import.</para>
+ </important>
- <sect3 xml:id="svn-advanced-use-maintaining-a-project-branch">
- <title>Maintaining a Project Branch</title>
+ <note>
+ <para>Patches to vendor code fall into two
+ categories:</para>
- <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/<replaceable>your-name</replaceable>/</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://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/projects/spif</userinput></screen>
+ <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>
- <para>To merge changes from HEAD back into the project
- branch:</para>
+ <listitem>
+ <para>&os; patches: these are patches that modify the
+ vendor code to address &os;-specific issues.</para>
+ </listitem>
+ </itemizedlist>
- <screen>&prompt.user; <userinput>cd copy_of_spif</userinput>
-&prompt.user; <userinput>svn merge svn+ssh://repo.freebsd.org/base/head</userinput>
-&prompt.user; <userinput>svn commit</userinput></screen>
+ <para>The nature of a patch dictates where it should be
+ committed:</para>
- <para>It is important to resolve any merge conflicts before
- committing.</para>
- <!--
- <para>To collapse everything back at the end:</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>
- <screen>&prompt.user; <userinput>svn write me</userinput></screen>
+ <listitem>
+ <para>&os; patches should be committed directly to
+ head.</para>
+ </listitem>
+ </itemizedlist>
+ </note>
- -->
- </sect3>
- </sect2>
+ <sect4>
+ <title>Preparing the Tree</title>
- <sect2>
- <title>Some Tips</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>
- <para>In commit logs etc., <quote>rev 179872</quote> should be
- spelled <quote>r179872</quote> as per convention.</para>
+ <sect5>
+ <title>Flattening</title>
- <para>Speeding up svn is possible by adding the following to
- <filename>~/.ssh/config</filename>:</para>
+ <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>
- <screen>Host *
-ControlPath ~/.ssh/sockets/master-%l-%r@%h:%p
-ControlMaster auto
-ControlPersist yes</screen>
+ <para>To flatten the <literal>pf</literal> tree:</para>
- <para>and then typing</para>
+ <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/dist/contrib/pf</replaceable></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>
- <screen><userinput>mkdir ~/.ssh/sockets</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>Checking out a working copy with a stock Subversion client
- without &os;-specific patches
- (<varname>OPTIONS_SET=FREEBSD_TEMPLATE</varname>) will mean
- that <literal>&dollar;FreeBSD&dollar;</literal> tags will not
- be expanded. Once the correct version has been installed,
- trick Subversion into expanding them like so:</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>
- <screen>&prompt.user; <userinput>svn propdel -R svn:keywords .</userinput>
-&prompt.user; <userinput>svn revert -R .</userinput></screen>
+ <sect5>
+ <title>Cleaning Up</title>
- <para>This will wipe out uncommitted patches.</para>
+ <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>
- <para>It is possible to automatically fill the "Sponsored by"
- and "MFC after" commit log fields by setting
- "freebsd-sponsored-by" and "freebsd-mfc-after" fields in the
- "[miscellany]" section of the
- <filename>~/.subversion/config</filename> configuration file.
- For example:</para>
+ <screen>&prompt.user; <userinput>svn propdel svn:keywords -R .</userinput>
+&prompt.user; <userinput>svn commit</userinput></screen>
+ </sect5>
- <programlisting>freebsd-sponsored-by = The FreeBSD Foundation
-freebsd-mfc-after = 2 weeks</programlisting>
- </sect2>
- </sect1>
+ <sect5>
+ <title>Bootstrapping Merge History</title>
- <sect1 xml:id="conventions">
- <title>Setup, Conventions, and Traditions</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>
- <para>There are a number of things to do as a new developer.
- The first set of steps is specific to committers only. These
- steps must be done by a mentor for those who are not
- committers.</para>
+ <screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput>
+&prompt.user; <userinput>svn merge --record-only svn+ssh://repo.freebsd.org/base/<replaceable>vendor/pf/dist@180876</replaceable> .</userinput>
+&prompt.user; <userinput>svn commit</userinput></screen>
+ </sect5>
+ </sect4>
- <sect2 xml:id="conventions-committers">
- <title>For New Committers</title>
+ <sect4>
+ <title>Importing New Sources</title>
- <para>Those who have been given commit rights to the &os;
- repositories must follow these steps.</para>
+ <para>With two commits&mdash;one for the import itself and
+ one for the tag&mdash;this step can optionally be repeated
+ for every upstream release between the last import and the
+ current import.</para>
- <itemizedlist xml:id="commit-notes">
- <listitem>
- <para>Get mentor approval before committing each of these
- changes!</para>
- </listitem>
+ <sect5>
+ <title>Preparing the Vendor Sources</title>
- <listitem>
- <para>The <filename>.ent</filename> and
- <filename>.xml</filename> files mentioned below exist in
- the &os; Documentation Project SVN repository at <link
- xlink:href="svn.FreeBSD.org/doc/"><literal>svn.FreeBSD.org/doc/</literal></link>.</para>
- </listitem>
+ <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>
- <listitem>
- <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. Verify that
- <filename>~/.subversion/config</filename> contains the
- necessary <quote>auto-props</quote> entries from
- <filename>auto-props.txt</filename> mentioned
- there.</para>
- </listitem>
+ <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>
- <listitem>
- <para>All <filename>src</filename> commits should go to
- &os.current; first before being merged to &os.stable;.
- The &os.stable; branch must maintain
- <acronym>ABI</acronym> and <acronym>API</acronym>
- compatibility with earlier versions of that branch. Do
- not merge changes that break this compatibility.</para>
- </listitem>
- </itemizedlist>
+ <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/dist</replaceable></userinput>
+&prompt.user; <userinput>svn list -R | grep -v '/$' | sort &gt;../old</userinput>
+&prompt.user; <userinput>cd <replaceable>../pf-4.3</replaceable></userinput>
+&prompt.user; <userinput>find . -type f | cut -c 3- | sort &gt;../new</userinput></screen>
- <procedure xml:id="commit-steps">
- <title>Steps for New Committers</title>
+ <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>
- <step>
- <title>Add an Author Entity</title>
+ <sect5>
+ <title>Importing into the Vendor Tree</title>
- <para><filename>doc/head/share/xml/authors.ent</filename>
- &mdash; Add an author entity. Later steps depend on this
- entity, and missing this step will cause the
- <filename>doc/</filename> build to fail. This is a
- relatively easy task, but remains a good first test of
- version control skills.</para>
- </step>
+ <para>Now, the sources must be copied into
+ <filename><replaceable>dist</replaceable></filename> and
+ the <command>svn add</command> and
+ <command>svn rm</command> commands should be used as
+ needed:</para>
- <step>
- <title>Update the List of Developers and
- Contributors</title>
+ <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/pf-4.3</replaceable></userinput>
+&prompt.user; <userinput>tar cf - . | tar xf - -C ../dist</userinput>
+&prompt.user; <userinput>cd <replaceable>../dist</replaceable></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><filename>doc/head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename>
- &mdash;
- Add an entry to the <quote>Developers</quote> section
- of the <link
- xlink:href="&url.articles.contributors;/staff-committers.html">Contributors
- List</link>. Entries are sorted by last name.</para>
-
- <para><filename>doc/head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename>
- &mdash; Remove the entry from the
- <quote>Additional Contributors</quote> section. Entries
- are sorted by first name.</para>
- </step>
+ <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>
- <step>
- <title>Add a News Item</title>
+ <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><filename>doc/head/share/xml/news.xml</filename>
- &mdash; Add an entry. Look for the other entries that
- announce new committers and follow the format. Use the
- date from the commit bit approval email from
- <email>core@FreeBSD.org</email>.</para>
- </step>
+ <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>
- <step>
- <title>Add a <acronym>PGP</acronym> Key</title>
+ <sect5>
+ <title>Tagging</title>
- <para><filename>doc/head/share/pgpkeys/pgpkeys.ent</filename>
- and
- <filename>doc/head/share/pgpkeys/pgpkeys-developers.xml</filename>
- - Add your <acronym>PGP</acronym> or
- Gnu<acronym>PG</acronym> key. Those who do not yet have a
- key should see <xref linkend="pgpkeys-creating"/>.</para>
-
- <para>&a.des.email; has written a shell script
- (<filename>doc/head/share/pgpkeys/addkey.sh</filename>) to
- make this easier. See the <link
- xlink:href="http://svnweb.FreeBSD.org/doc/head/share/pgpkeys/README">README</link>
- file for more information.</para>
-
- <para>Use
- <filename>doc/head/share/pgpkeys/checkkey.sh</filename> to
- verify that keys meet minimal best-practices
- standards.</para>
-
- <para>After adding and checking a key, add both updated
- files to source control and then commit them. Entries in
- this file are sorted by last name.</para>
+ <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>
- <note>
- <para>It is very important to have a current
- <acronym>PGP</acronym>/Gnu<acronym>PG</acronym> key in
- the repository. The key may be required for positive
- identification of a committer. For example, the
- &a.admins; might need it 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>
- </step>
+ <screen>&prompt.user; <userinput>svn cp svn+ssh://repo.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> svn+ssh://repo.freebsd.org/base/<replaceable>vendor/pf/4.3</replaceable></userinput></screen>
- <step>
- <title>Update Mentor and Mentee Information</title>
+ <para>Once that is complete, <command>svn up</command> the
+ working copy of
+ <filename><replaceable>vendor/pf</replaceable></filename>
+ to get the new tag, although this is rarely
+ needed.</para>
- <para><filename>base/head/share/misc/committers-<replaceable>repository</replaceable>.dot</filename>
- &mdash; Add an entry to the current committers section,
- where <replaceable>repository</replaceable> is
- <literal>doc</literal>, <literal>ports</literal>, or
- <literal>src</literal>, depending on the commit privileges
- granted.</para>
-
- <para>Add an entry for each additional mentor/mentee
- relationship in the bottom section.</para>
- </step>
-
- <step>
- <title>Generate a <application>Kerberos</application>
- Password</title>
-
- <para>See <xref linkend="kerberos-ldap"/> to generate or
- set a <application>Kerberos</application> for use with
- other &os; services like the bug tracking database.</para>
- </step>
-
- <step>
- <title>Optional: Enable Wiki Account</title>
-
- <para><link xlink:href="http://wiki.freebsd.org">&os;
- Wiki</link> Account &mdash; A wiki account allows
- sharing projects and ideas. Those who do not yet have an
- account can contact <email>clusteradm@FreeBSD.org</email>
- to obtain one.</para>
- </step>
-
- <step>
- <title>Optional: Update Wiki Information</title>
-
- <para>Wiki Information - After gaining access to the wiki,
- some people add entries to the <link
- xlink:href="http://wiki.freebsd.org/HowWeGotHere">How We
- Got Here</link>,
- <link xlink:href="http://wiki.freebsd.org/IrcNicks">Irc
- Nicks</link>, and <link
- xlink:href="https://wiki.freebsd.org/DogsOfFreeBSD">Dogs
- of FreeBSD</link> pages.</para>
- </step>
-
- <step>
- <title>Optional: Update Ports with Personal
- Information</title>
-
- <para><filename>ports/astro/xearth/files/freebsd.committers.markers</filename>
- and
- <filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename>
- - Some people add entries for themselves to these files to
- show where they are located or the date of their
- birthday.</para>
- </step>
-
- <step>
- <title>Optional: Prevent Duplicate Mailings</title>
-
- <para>Subscribers to &a.svn-src-all.name;,
- &a.svn-ports-all.name; or &a.svn-doc-all.name; might wish
- to unsubscribe to avoid receiving duplicate copies of
- commit messages and followups.</para>
- </step>
- </procedure>
- </sect2>
-
- <sect2 xml:id="conventions-everyone">
- <title>For Everyone</title>
-
- <procedure xml:id="conventions-everyone-steps">
- <step>
- <para>Introduce yourself to the other developers, otherwise
- no one will have any idea who you are or what you are
- working on. The introduction need not be a comprehensive
- biography, just write a paragraph or two about who you
- are, what you plan to be working on as a developer in
- &os;, and who will be your mentor. Email this to the
- &a.developers; and you will be on your way!</para>
- </step>
-
- <step>
- <para>Log into <systemitem>freefall.FreeBSD.org</systemitem>
- and create a
- <filename>/var/forward/<replaceable>user</replaceable></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>freefall</systemitem> may get truncated
- without warning if space needs to be freed, 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>
- </step>
- </procedure>
-
- <note>
- <para>Those who are developers but not committers 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 have a mentor assigned to them for
- the first few months. A mentor is responsible for teaching
- the mentee the rules and conventions of the project and
- guiding their first steps in the developer community. The
- mentor is also personally responsible for the mentee's actions
- during this initial period.</para>
-
- <para>For committers: do not commit anything without first
- getting mentor approval. Document that approval with an
- <literal>Approved by:</literal> line in the commit
- message.</para>
-
- <para>When the mentor decides that a mentee has learned the
- ropes and is ready to commit on their own, the mentor
- announces it with a commit to
- <filename>conf/mentors</filename>. This file is in the
- <filename>svnadmin</filename> branch of each
- repository:</para>
-
- <informaltable frame="none">
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><literal>src</literal></entry>
- <entry><filename>base/svnadmin/conf/mentors</filename></entry>
- </row>
-
- <row>
- <entry><literal>doc</literal></entry>
- <entry><filename>doc/svnadmin/conf/mentors</filename></entry>
- </row>
-
- <row>
- <entry><literal>ports</literal></entry>
- <entry><filename>ports/svnadmin/conf/mentors</filename></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </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 cannot 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 committing, 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>While under mentorship, get mentor approval before
- the commit. Enter the mentor's username in this field,
- and note that they are a mentor:</para>
-
- <screen>Approved by: <userinput><replaceable>username-of-mentor</replaceable> <literal>(mentor)</literal></userinput></screen>
-
- <para>If a team approved these commits then include the
- team name followed by the username of the approver in
- parentheses. For example:</para>
-
- <screen>Approved by: <userinput><literal>re</literal> (<replaceable>username</replaceable>)</userinput></screen></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>Relnotes:</literal></entry>
- <entry>If the change is a candidate for inclusion in
- the release notes for the next release from the branch,
- set to <literal>yes</literal>.</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>
-
- <row>
- <entry><literal>Differential Revision:</literal></entry>
- <entry>The full URL of the Phabricator review. This line
- <emphasis>must be the last line</emphasis>. For example:
- <literal>https://reviews.freebsd.org/D1708</literal>.</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: 12345
- Submitted by: John Smith &lt;John.Smith@example.com&gt;</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: 54321
-Submitted by: John Smith &lt;John.Smith@example.com&gt;
-Reviewed by: -arch
-Obtained from: NetBSD
-MFC after: 1 month
-Relnotes: yes</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="tracking.license.grants">
- <title>Keeping Track of Licenses Granted to the &os;
- Project</title>
-
- <para>Various software or data exist in the repositories where
- the &os; project has been granted a special licence to be able
- to use them. A case in point are the Terminus fonts for use
- with &man.vt.4;. Here the author Dimitar Zhekov has allowed us
- to use the "Terminus BSD Console" font under a 2-clause BSD
- license rather than the regular Open Font License he normally
- uses.</para>
-
- <para>It is clearly sensible to keep a record of any such
- license grants. To that end, the &a.core; has decided to keep
- an archive of them. Whenever the &os; project is granted a
- special license we require the &a.core; to be notified. Any
- developers involved in arranging such a license grant, please
- send details to the &a.core; including:</para>
-
- <itemizedlist>
- <listitem>
- <para>Contact details for people or organizations granting the
- special license.</para>
- </listitem>
-
- <listitem>
- <para>What files, directories etc. in the repositories are
- covered by the license grant including the revision numbers
- where any specially licensed material was committed.</para>
- </listitem>
-
- <listitem>
- <para>The date the license comes into effect from. Unless
- otherwise agreed, this will be the date the license was
- issued by the authors of the software in question.</para>
- </listitem>
-
- <listitem>
- <para>The license text.</para>
- </listitem>
-
- <listitem>
- <para>A note of any restrictions, limitations or exceptions
- that apply specifically to &os;'s usage of the licensed
- material.</para>
- </listitem>
-
- <listitem>
- <para>Any other relevant information.</para>
- </listitem>
- </itemizedlist>
-
- <para>Once the &a.core; is satisfied that all the necessary
- details have been gathered and are correct, the secretary will
- send a PGP-signed acknowledgement of receipt including the
- license details. This receipt will be persistently archived and
- serve as our permanent record of the license grant.</para>
-
- <para>The license archive should contain only details of license
- grants; this is not the place for any discussions around
- licensing or other subjects. Access to data within the license
- archive will be available on request to the &a.core;.</para>
- </sect1>
+ <para>If creating the tag in the working copy of the tree,
+ <command>svn:mergeinfo</command> results must be
+ removed:</para>
- <sect1 xml:id="developer.relations">
- <title>Developer Relations</title>
+ <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf</replaceable></userinput>
+&prompt.user; <userinput>svn cp dist 4.3</userinput>
+&prompt.user; <userinput>svn propdel svn:mergeinfo -R 4.3</userinput></screen>
+ </sect5>
+ </sect4>
- <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><replaceable>repository</replaceable>-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. An example script that lists
- each person who has committed to
- a given file along with the number of commits each person has
- made can be found at on <systemitem>freefall</systemitem> at
- <filename>~eadler/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>
+ <sect4>
+ <title>Merging to Head</title>
- <note>
- <para>Avoid sending private emails to maintainers. Other people
- might be interested in the conversation, not just the final
- output.</para>
- </note>
+ <screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput>
+&prompt.user; <userinput>svn up</userinput>
+&prompt.user; <userinput>svn merge --accept=postpone svn+ssh://repo.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> .</userinput></screen>
- <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 &ndash; with a version control system we can
- always change it back.</para>
+ <para>The <literal>--accept=postpone</literal> tells
+ Subversion that it should not complain because merge
+ conflicts will be taken care of manually.</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>
+ <tip xml:id="svn-advanced-use-vendor-imports-pre-svn">
+ <para>The <command>cvs2svn</command> changeover occurred
+ on June 3, 2008. When performing vendor merges for
+ packages which were already present and converted by the
+ <command>cvs2svn</command> process, the command used to
+ merge
+ <filename>/vendor/<replaceable>package_name</replaceable>/dist</filename>
+ to
+ <filename>/head/<replaceable>package_location</replaceable></filename>
+ (for example,
+ <filename>head/contrib/sendmail</filename>) must use
+ <option>-c <replaceable>REV</replaceable></option> to
+ indicate the revision to merge from the
+ <filename>/vendor</filename> tree. For example:</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>
+ <screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/base/head/contrib/<replaceable>sendmail</replaceable></userinput>
+&prompt.user; <userinput>cd sendmail</userinput>
+&prompt.user; <userinput>svn merge -c r<replaceable>261190</replaceable> ^/vendor/<replaceable>sendmail/dist</replaceable> .</userinput></screen>
- <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><literal>^</literal> is an alias for the
+ repository path.</para>
+ </tip>
- <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>
+ <note>
+ <para>If using the <application>Zsh</application> shell,
+ the <literal>^</literal> must be escaped with
+ <literal>\</literal>. This means
+ <literal>^/head</literal> should be
+ <literal>\^/head</literal>.</para>
+ </note>
- <sect1 xml:id="if-in-doubt">
- <title>If in Doubt...</title>
+ <para>It is necessary to resolve any merge conflicts.</para>
- <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>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>
- <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>
+ <screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=svn+ssh://repo.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> --new=.</userinput></screen>
- <para>For project specific or administrative questions you should
- ask, in order:</para>
+ <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>
- <itemizedlist>
- <listitem>
- <para>Your mentor or former mentor.</para>
- </listitem>
+ <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>
- <listitem>
- <para>An experienced committer on IRC, email, etc.</para>
- </listitem>
+ <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>
- <listitem>
- <para>Any team with a "hat", as they should give you a
- definitive answer.</para>
- </listitem>
+ <sect4>
+ <title>Committing the Vendor Import</title>
- <listitem>
- <para>If still not sure, ask on &a.developers;.</para>
- </listitem>
- </itemizedlist>
+ <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>
- <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>
+ <sect4>
+ <title>From Scratch</title>
- <sect1 xml:id="bugzilla">
- <title>Bugzilla</title>
+ <sect5>
+ <title>Importing into the Vendor Tree</title>
- <para>The &os; Project utilizes
- <application>Bugzilla</application> for tracking bugs and change
- requests. Be sure that if you commit a fix or suggestion found
- in the PR database to close it. It is also considered nice if
- you take time to close any PRs associated with your commits, if
- appropriate.</para>
+ <para>This section is an example of importing and tagging
+ <application>byacc</application> into
+ <filename>head</filename>.</para>
- <para>Committers with
- non-<systemitem class="domainname">&os;.org</systemitem>
- Bugzilla accounts can have the old account merged with the
- <systemitem class="domainname">&os;.org</systemitem> account by
- entering a new bug. Choose
- <literal>Supporting Services</literal> as the Product, and
- <literal>Bug Tracker</literal> as the Component.</para>
+ <para>First, prepare the directory in
+ <filename>vendor</filename>:</para>
- <para>You can find out more about
- <application>Bugzilla</application> at:</para>
+ <screen>&prompt.user; <userinput>svn co --depth immediates <replaceable>$FSVN/vendor</replaceable></userinput>
+&prompt.user; <userinput>cd <replaceable>vendor</replaceable></userinput>
+&prompt.user; <userinput>svn mkdir <replaceable>byacc</replaceable></userinput>
+&prompt.user; <userinput>svn mkdir <replaceable>byacc/dist</replaceable></userinput></screen>
- <itemizedlist>
- <listitem>
- <para><link
- xlink:href="&url.articles.pr-guidelines;/index.html">&os;
- Problem Report Handling Guidelines</link></para>
- </listitem>
+ <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>
- <listitem>
- <para><link
- xlink:href="&url.base;/support.html">http://www.FreeBSD.org/support.html</link></para>
- </listitem>
- </itemizedlist>
- </sect1>
+ <screen>&prompt.user; <userinput>svn cp -m <replaceable>"Tag byacc 20120115"</replaceable> <replaceable>$FSVN/vendor/byacc/dist</replaceable> <replaceable>$FSVN/vendor/byacc/20120115</replaceable></userinput></screen>
+ </sect5>
- <sect1>
- <title>Phabricator</title>
+ <sect5>
+ <title>Merging to <literal>head</literal></title>
- <para>The &os; Project utilizes <link
- xlink:href="https://reviews.freebsd.org">Phabricator</link>
- for code review requests. See the <link
- xlink:href="https://wiki.freebsd.org/CodeReview">CodeReview</link>
- wiki page for details.</para>
+ <para>Due to this being a new file, copy it for the
+ merge:</para>
- </sect1>
+ <screen>&prompt.user; <userinput>svn cp -m <replaceable>"Import byacc to contrib"</replaceable> <replaceable>$FSVN/vendor/byacc/dist</replaceable> <replaceable>$FSVN/head/contrib/byacc</replaceable></userinput></screen>
- <sect1 xml:id="people">
- <title>Who's Who</title>
+ <para>Working normally on newly imported sources is still
+ possible.</para>
+ </sect5>
+ </sect4>
+ </sect3>
- <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>
+ <sect3 xml:id="svn-advanced-use-reverting-a-commit">
+ <title>Reverting a Commit</title>
- <variablelist>
- <varlistentry>
- <term>&a.doceng;</term>
+ <para>Reverting a commit to a previous version is fairly
+ easy:</para>
- <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 <application>subversion</application> 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>
+ <screen>&prompt.user; <userinput>svn merge -r179454:179453 ROADMAP.txt</userinput>
+&prompt.user; <userinput>svn commit</userinput></screen>
- <varlistentry>
- <term>&a.bde.email;</term>
+ <para>Change number syntax, with negative meaning a reverse
+ change, can also be used:</para>
- <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>
+ <screen>&prompt.user; <userinput>svn merge -c -179454 ROADMAP.txt</userinput>
+&prompt.user; <userinput>svn commit</userinput></screen>
- <varlistentry>
- <term>&a.re.members.email;</term>
+ <para>This can also be done directly in the repository:</para>
- <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>
+ <screen>&prompt.user; <userinput>svn merge -r179454:179453 svn+ssh://repo.freebsd.org/base/ROADMAP.txt</userinput></screen>
- <varlistentry>
- <term>&a.so.email;</term>
+ <note>
+ <para>It is important to ensure that the mergeinfo
+ is correct when reverting a file in order to permit
+ <command>svn mergeinfo --show-revs=eligible</command> to work as
+ expected.</para>
+ </note>
- <listitem>
- <para>&a.so; is the
- <link xlink:href="&url.base;/security/">&os; Security
- Officer</link> and oversees the
- &a.security-officer;.</para>
- </listitem>
- </varlistentry>
+ <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>
- <varlistentry>
- <term>&a.wollman.email;</term>
+ <screen>&prompt.user; <userinput>svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454</userinput>
+&prompt.user; <userinput>svn commit</userinput></screen>
- <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>
+ <para>or, equally:</para>
- <varlistentry>
- <term>&a.committers;</term>
+ <screen>&prompt.user; <userinput>svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 svn+ssh://repo.freebsd.org/base</userinput></screen>
- <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>
+ <para>Do <emphasis>not</emphasis> simply recreate the file
+ manually and <command>svn add</command> it&mdash;this will
+ cause history to be lost.</para>
+ </sect3>
- <varlistentry>
- <term>&a.developers;</term>
+ <sect3 xml:id="svn-advanced-use-fixing-mistakes">
+ <title>Fixing Mistakes</title>
- <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 expected not to
- not publish or forward messages from the
- &a.developers; outside the list membership without
- permission of all of the authors. 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 for any technical discussion.
- 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>
+ <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>
- <sect1 xml:id="ssh.guide">
- <title>SSH Quick-Start Guide</title>
+ <para>Mistakes will happen but,
+ they can generally be fixed without
+ disruption.</para>
- <procedure>
- <step>
- <para>If you do not wish to type your password in every time
- you use &man.ssh.1;, and you use 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>
+ <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>
- <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>
+ <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>
- <important>
- <para>Only <acronym>ECDSA</acronym>,
- <acronym>Ed25519</acronym> or <acronym>RSA</acronym> keys
- are supported.</para>
- </important>
- </step>
+ <sect3 xml:id="svn-advanced-use-setting-up-svnsync">
+ <title>Setting up a <application>svnsync</application>
+ Mirror</title>
- <step>
- <para>Send your public key
- (<filename>$HOME/.ssh/id_ecdsa.pub</filename>,
- <filename>$HOME/.ssh/id_ed25519.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
- <filename><replaceable>yourlogin</replaceable></filename>
- in
- <filename>/etc/ssh-keys/</filename> on
- <systemitem>freefall</systemitem>.</para>
- </step>
- </procedure>
+ <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>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>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>
- <para>Test by doing something such as <command>ssh
- freefall.FreeBSD.org ls /usr</command>.</para>
+ <screen>&prompt.user; <userinput>rsync -va --partial --progress freefall:/home/peter/svnmirror-base-r179637.tbz2 .</userinput></screen>
- <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>
+ <screen>&prompt.user; <userinput>rsync -va --partial --progress rsync://repoman.freebsd.org:50873/svnseed/svnmirror-base-r215629.tar.xz .</userinput></screen>
- <para>For information on adding, changing, or removing &man.ssh.1;
- keys, see <uri
- xlink:href="https://wiki.freebsd.org/clusteradm/ssh-keys">this
- article</uri>.</para>
- </sect1>
+ <screen>&prompt.user; <userinput>fetch ftp://ftp.freebsd.org/pub/FreeBSD/development/subversion/svnmirror-base-r221445.tar.xz</userinput></screen>
- <sect1 xml:id="coverity">
- <title>&coverity; Availability for &os; Committers</title>
+ <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>
- <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>
+ <screen>&prompt.user; <userinput>svnsync sync file:///home/svnmirror/base</userinput></screen>
- <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>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>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>
+ <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>
- <sect1 xml:id="rules">
- <title>The &os; Committers' Big List of Rules</title>
+ <screen>&prompt.user; <userinput>svn proplist -v --revprop -r 0 file:///home/svnmirror/base</userinput></screen>
- <para>Everyone involved with the &os; project is expected to
- abide by the <emphasis>Code of Conduct</emphasis> available from
- <link xlink:href="&url.base;/internal/code-of-conduct.html"
- >http://www.FreeBSD.org/internal/code-of-conduct.html</link>.
- As committers, you form the public face of the project, and how
- you behave has a vital impact on the public perception of it.
- This guide expands on the parts of the
- <emphasis>Code of Conduct</emphasis> specific to
- committers.</para>
+ <para>Use <literal>propset</literal> to change things.</para>
+ </sect3>
- <orderedlist>
- <listitem>
- <para>Respect other committers.</para>
- </listitem>
+ <sect3 xml:id="svn-advanced-use-committing-high-ascii-data">
+ <title>Committing High-<acronym>ASCII</acronym> Data</title>
- <listitem>
- <para>Respect other contributors.</para>
- </listitem>
+ <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>
- <listitem>
- <para>Discuss any significant change
- <emphasis>before</emphasis> committing.</para>
- </listitem>
+ <screen>&prompt.user; <userinput>svn propset fbsd:notbinary yes foo.data</userinput></screen>
+ </sect3>
- <listitem>
- <para>Respect existing maintainers (if listed in the
- <varname>MAINTAINER</varname> field in
- <filename>Makefile</filename> or in
- <filename>MAINTAINER</filename> in the top-level
- directory).</para>
- </listitem>
+ <sect3 xml:id="svn-advanced-use-maintaining-a-project-branch">
+ <title>Maintaining a Project Branch</title>
- <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>
+ <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>
- <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>
+ <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/<replaceable>your-name</replaceable>/</filename>.
+ <link
+ xlink:href="http://svnweb.freebsd.org/base/projects/GUIDELINES.txt">This
+ page</link> contains further details.</para>
- <listitem>
- <para>Do not fight in public with other committers; it looks
- bad.</para>
- </listitem>
+ <para>To create a project branch:</para>
- <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>
+ <screen>&prompt.user; <userinput>svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/projects/spif</userinput></screen>
- <listitem>
- <para>When in doubt on any procedure, ask first!</para>
- </listitem>
+ <para>To merge changes from HEAD back into the project
+ branch:</para>
- <listitem>
- <para>Test your changes before committing them.</para>
- </listitem>
+ <screen>&prompt.user; <userinput>cd copy_of_spif</userinput>
+&prompt.user; <userinput>svn merge svn+ssh://repo.freebsd.org/base/head</userinput>
+&prompt.user; <userinput>svn commit</userinput></screen>
- <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>It is important to resolve any merge conflicts before
+ committing.</para>
+ <!--
+ <para>To collapse everything back at the end:</para>
- <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>
+ <screen>&prompt.user; <userinput>svn write me</userinput></screen>
- <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>
+ -->
+ </sect3>
+ </sect2>
<sect2>
- <title>Details</title>
+ <title>Some Tips</title>
- <orderedlist>
- <listitem xml:id="respect">
- <para>Respect other committers.</para>
+ <para>In commit logs etc., <quote>rev 179872</quote> should be
+ spelled <quote>r179872</quote> as per convention.</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>
+ <para>Speeding up svn is possible by adding the following to
+ <filename>~/.ssh/config</filename>:</para>
- <listitem>
- <para>Respect other contributors.</para>
+ <screen>Host *
+ControlPath ~/.ssh/sockets/master-%l-%r@%h:%p
+ControlMaster auto
+ControlPersist yes</screen>
- <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>
+ <para>and then typing</para>
- <listitem>
- <para>Discuss any significant change
- <emphasis>before</emphasis> committing.</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>&dollar;FreeBSD&dollar;</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>
- <para>The repository is not where changes should be
- initially submitted for correctness or argued over, that
- should happen first in the mailing lists or by use of the
- Phabricator service 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>surprised</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>It is possible to automatically fill the "Sponsored by"
+ and "MFC after" commit log fields by setting
+ "freebsd-sponsored-by" and "freebsd-mfc-after" fields in the
+ "[miscellany]" section of the
+ <filename>~/.subversion/config</filename> configuration file.
+ For example:</para>
- <para>When in doubt, ask for review!</para>
- </listitem>
+ <programlisting>freebsd-sponsored-by = The FreeBSD Foundation
+freebsd-mfc-after = 2 weeks</programlisting>
+ </sect2>
+ </sect1>
- <listitem>
- <para>Respect existing maintainers if listed.</para>
+ <sect1 xml:id="commit-log-message">
+ <title>Commit Log Messages</title>
- <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>
+ <para>This section contains some suggestions and traditions for
+ how commit logs are formatted.</para>
- <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>
+ <para>As well as including an informative message with each
+ commit you may need to include some additional
+ information.</para>
- <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/9.3</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>
+ <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>
- <listitem>
- <para>Do not fight in public with other committers; it looks
- bad.</para>
+ <para>The key words or phrases are:</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 or other private communications to public
- mailing lists, mail aliases, instant messaging channels or
- social media sites. 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 third party to resolve the
- dispute. All parties involved must then agree to be bound
- by the decision reached by this third party.</para>
- </listitem>
+ <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 cannot understand more than
+ one.</entry>
+ </row>
- <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>
+ <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>
- <listitem>
- <para>When in doubt on any procedure, ask first!</para>
+ <para>If the submitter is the maintainer of the port
+ to which you are committing, include "(maintainer)"
+ after the email address.</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>
+ <para>Avoid obfuscating the email address of the
+ submitter as this adds additional work when searching
+ logs.</para>
+ </entry>
+ </row>
- <listitem>
- <para>Test your changes before committing them.</para>
+ <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>
- <!-- 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>
+ <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>
- <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>While under mentorship, get mentor approval before
+ the commit. Enter the mentor's username in this field,
+ and note that they are a mentor:</para>
- <para>Contact the &a.core; if you wish to take up
- maintainership of an unmaintained part of the tree.</para>
- </listitem>
- </orderedlist>
- </sect2>
+ <screen>Approved by: <userinput><replaceable>username-of-mentor</replaceable> <literal>(mentor)</literal></userinput></screen>
- <sect2>
- <title>Policy on Multiple Architectures</title>
+ <para>If a team approved these commits then include the
+ team name followed by the username of the approver in
+ parentheses. For example:</para>
- <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>
+ <screen>Approved by: <userinput><literal>re</literal> (<replaceable>username</replaceable>)</userinput></screen></entry>
+ </row>
- <blockquote>
- <para>Our 32-bit reference platform is &arch.i386;, and our
- 64-bit reference platform is &arch.amd64;. 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>
+ <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>
- <para>The &arch.i386; and &arch.amd64; 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>
+ <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>
- <para>We will continue to re-evaluate this policy as cost and
- availability of the 64-bit platforms change.</para>
+ <row>
+ <entry><literal>Relnotes:</literal></entry>
+ <entry>If the change is a candidate for inclusion in
+ the release notes for the next release from the branch,
+ set to <literal>yes</literal>.</entry>
+ </row>
- <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>
+ <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>
- <sect2>
- <title>Other Suggestions</title>
+ <row>
+ <entry><literal>Differential Revision:</literal></entry>
+ <entry>The full URL of the Phabricator review. This line
+ <emphasis>must be the last line</emphasis>. For example:
+ <literal>http://reviews.freebsd.org/D1708</literal>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
- <para>When committing documentation changes, use a spell checker
- before committing. For all XML docs, verify that the
- formatting directives are correct by running
- <command>make lint</command> and
- <package>textproc/igor</package>.</para>
+ <example>
+ <title>Commit Log for a Commit Based on a PR</title>
- <para>For manual pages, run <package>sysutils/manck</package>
- and <package>textproc/igor</package>
- 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>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>
- <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> .
- 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>
+ <programlisting>...
- <sect2>
- <title>Deprecating Features</title>
+ PR: 12345
+ Submitted by: John Smith &lt;John.Smith@example.com&gt;</programlisting>
+ </example>
- <para>When it is necessary to remove functionality from software
- in the base system the following guidelines should be followed
- whenever possible:</para>
+ <example>
+ <title>Commit Log for a Commit Needing Review</title>
- <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>
+ <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>
- <listitem>
- <para>The option, utility, or interface is preserved until
- the next major (point zero) release.</para>
- </listitem>
+ <programlisting>...
- <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>
+ Reviewed by: -arch</programlisting>
+ </example>
- <sect2>
- <title>Privacy and Confidentiality</title>
+ <example>
+ <title>Commit Log for a Commit Needing Approval</title>
- <orderedlist>
- <listitem>
- <para>Most &os; business is done in public.</para>
+ <para>You want to commit a port. You have collaborated with
+ the listed MAINTAINER, who has told you to go ahead and
+ commit.</para>
- <para>&os; is an <emphasis>open</emphasis> project. Which
- means that not only can anyone use the source code, but
- that most of the development process is open to public
- scrutiny.</para>
- </listitem>
+ <programlisting>...
- <listitem>
- <para>Certain sensitive matters must remain private or
- held under embargo.</para>
+ Approved by: <replaceable>abc</replaceable> (maintainer)</programlisting>
- <para>There unfortunately cannot be complete transparency.
- As a &os; developer you will have a certain degree of
- privileged access to information. Consequently you are
- expected to respect certain requirements for
- confidentiality. Sometimes the need for confidentiality
- comes from external collaborators or has a specific time
- limit. Mostly though, it is a matter of not releasing
- private communications.</para>
- </listitem>
+ <para>Where <replaceable>abc</replaceable> is the account name
+ of the person who approved.</para>
+ </example>
- <listitem>
- <para>The Security Officer has sole control over the
- release of security advisories.</para>
+ <example>
+ <title>Commit Log for a Commit Bringing in Code from
+ OpenBSD</title>
- <para>Where there are security problems that affect many
- different operating systems, &os; frequently depends on
- early access in order to be able to prepare advisories for
- coordinated release. Unless &os; developers can be
- trusted to maintain security, such early access will not
- be made available. The Security Officer is responsible
- for controlling pre-release access to information about
- vulnerabilities, and for timing the release of all
- advisories. He may request help under condition of
- confidentiality from any developer with relevant knowledge
- in order to prepare security fixes.</para>
- </listitem>
+ <para>You want to commit some code based on work done in the
+ OpenBSD project.</para>
- <listitem>
- <para>Communications with Core are kept confidential for as
- long as necessary.</para>
+ <programlisting>...
- <para>Communications to core will initially be treated as
- confidential. Eventually however, most of Core's business
- will be summarized into the monthly or quarterly core
- reports. Care will be taken to avoid publicising any
- sensitive details. Records of some particularly sensitive
- subjects may not be reported on at all and will be
- retained only in Core's private archives.</para>
- </listitem>
+ Obtained from: OpenBSD</programlisting>
+ </example>
- <listitem>
- <para>Non-disclosure Agreements may be required for access
- to certain commercially sensitive data.</para>
+ <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>Access to certain commercially sensitive data may
- only be available under a Non-Disclosure Agreement. The
- FreeBSD Foundation legal staff must be consulted before
- any binding agreements are entered into.</para>
- </listitem>
+ <para>You want to commit some code which will be merged from
+ &os.current; into the &os.stable; branch after two
+ weeks.</para>
- <listitem>
- <para>Private communications should not be made
- public without permission.</para>
+ <programlisting>...
- <para>Beyond the specific requirements above there is a
- general expectation not to publish private communications
- between developers without the consent of all parties
- involved. Ask permission before forwarding a message onto
- a public mailing list, or posting it to a forum or website
- that can be accessed by other than the original
- correspondents.</para>
- </listitem>
+MFC after: <replaceable>2 weeks</replaceable></programlisting>
- <listitem>
- <para>Communications on project-only or restricted access
- channels should be treated as private.</para>
+ <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>Similarly to personal communications, certain
- internal communications channels, including &os; Committer
- only mailing lists and restricted access IRC channels
- should be considered as private communications. You need
- permission in order to publish material from these
- sources.</para>
- </listitem>
+ <para>In many cases you may need to combine some of these.</para>
- <listitem>
- <para>Core may approve publication.</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>Where it is impractical to obtain permission due to
- the number of correspondents or where permission to
- publish is unreasonably withheld, Core may approve release
- of such private matters that merit more general
- publication.</para>
- </listitem>
- </orderedlist>
- </sect2>
- </sect1>
+ <para>The extra information to include in the commit would look
+ something like</para>
- <sect1 xml:id="archs">
- <title>Support for Multiple Architectures</title>
+ <example>
+ <title>Example Combined Commit Log</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>
+ <programlisting>PR: 54321
+Submitted by: John Smith &lt;John.Smith@example.com&gt;
+Reviewed by: -arch
+Obtained from: NetBSD
+MFC after: 1 month
+Relnotes: yes</programlisting>
+ </example>
+ </sect1>
- <sect2>
- <title>Statement of General Intent</title>
+ <sect1 xml:id="pref-license">
+ <title>Preferred License for New Files</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>Currently the &os; Project suggests and uses the following
+ text as the preferred license scheme:</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>
+ <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>
- <sect2>
- <title>Tier 1: Fully Supported Architectures</title>
+ <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>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>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>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>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>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>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>
- <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>
+ <sect1 xml:id="tracking.license.grants">
+ <title>Keeping Track of Licenses Granted to the &os;
+ Project</title>
- <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>Various software or data exist in the repositories where
+ the &os; project has been granted a special licence to be able
+ to use them. A case in point are the Terminus fonts for use
+ with &man.vt.4;. Here the author Dimitar Zhekov has allowed us
+ to use the "Terminus BSD Console" font under a 2-clause BSD
+ license rather than the regular Open Font License he normally
+ uses.</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>It is clearly sensible to keep a record of any such
+ license grants. To that end, the &a.core; has decided to keep
+ an archive of them. Whenever the &os; project is granted a
+ special license we require the &a.core; to be notified. Any
+ developers involved in arranging such a license grant, please
+ send details to the &a.core; including:</para>
- <para>Current Tier 1 platforms are &arch.i386; and
- &arch.amd64;.</para>
- </sect2>
+ <itemizedlist>
+ <listitem>
+ <para>Contact details for people or organizations granting the
+ special license.</para>
+ </listitem>
- <sect2>
- <title>Tier 2: Developmental Architectures</title>
+ <listitem>
+ <para>What files, directories etc. in the repositories are
+ covered by the license grant including the revision numbers
+ where any specially licensed material was committed.</para>
+ </listitem>
- <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
- maintainers are 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>
+ <listitem>
+ <para>The date the license comes into effect from. Unless
+ otherwise agreed, this will be the date the license was
+ issued by the authors of the software in question.</para>
+ </listitem>
- <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>
+ <listitem>
+ <para>The license text.</para>
+ </listitem>
- <para>Tier 2 architectures have basic 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>
+ <listitem>
+ <para>A note of any restrictions, limitations or exceptions
+ that apply specifically to &os;'s usage of the licensed
+ material.</para>
+ </listitem>
- <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 relatively recent. It should be
- integrated into the &os; documentation.</para>
+ <listitem>
+ <para>Any other relevant information.</para>
+ </listitem>
+ </itemizedlist>
- <para>Current Tier 2 platforms are &arch.arm;, &arch.arm64;,
- &arch.ia64; (through &os; 10),
- &arch.pc98;, &arch.powerpc;, and &arch.sparc64;.</para>
- </sect2>
+ <para>Once the &a.core; is satisfied that all the necessary
+ details have been gathered and are correct, the secretary will
+ send a PGP-signed acknowledgement of receipt including the
+ license details. This receipt will be persistently archived and
+ serve as our permanent record of the license grant.</para>
- <sect2>
- <title>Tier 3: Experimental Architectures</title>
+ <para>The license archive should contain only details of license
+ grants; this is not the place for any discussions around
+ licensing or other subjects. Access to data within the license
+ archive will be available on request to the &a.core;.</para>
+ </sect1>
- <para>Tier 3 platforms are not supported by the security officer
- and release engineering teams. At the discretion of the
- toolchain maintainers, 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. Initial support for Tier 3 platforms should be worked on
- in external SCM repositories.
- The transition to &os;'s subversion should take place after
- the platform boots multi-user on hardware; sharing via
- subversion is needed for wider exposure; and multiple
- developers are actively working on the platform.
- 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>
+ <sect1 xml:id="bugzilla">
+ <title>Bugzilla</title>
- <para>Tier 3 platforms may have ports support, either integrated
- or external, but do not require it.</para>
+ <para>The &os; Project utilizes
+ <application>Bugzilla</application> for tracking bugs and change
+ requests. Be sure that if you commit a fix or suggestion found
+ in the PR database to close it. It is also considered nice if
+ you take time to close any PRs associated with your commits, if
+ appropriate.</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>Committers with
+ non-<systemitem class="domainname">&os;.org</systemitem>
+ Bugzilla accounts can have the old account merged with the
+ <systemitem class="domainname">&os;.org</systemitem> account by
+ entering a new bug. Choose
+ <literal>Supporting Services</literal> as the Product, and
+ <literal>Bug Tracker</literal> as the Component.</para>
- <para>Current Tier 3 platforms are &arch.mips;, and
- &arch.riscv;.</para>
- </sect2>
+ <para>You can find out more about
+ <application>Bugzilla</application> at:</para>
- <sect2>
- <title>Tier 4: Unsupported Architectures</title>
+ <itemizedlist>
+ <listitem>
+ <para><link
+ xlink:href="&url.articles.pr-guidelines;/index.html">&os;
+ Problem Report Handling Guidelines</link></para>
+ </listitem>
- <para>Tier 4 systems are not supported in any form by the
- project.</para>
+ <listitem>
+ <para><link
+ xlink:href="&url.base;/support.html">http://www.freebsd.org/support.html</link></para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
- <para>All systems not otherwise classified into a support tier
- are Tier 4 systems. The &arch.ia64; platform is transitioning
- to Tier 4 status in &os; 11.</para>
- </sect2>
+ <sect1 xml:id="coverity">
+ <title>&coverity; Availability for &os; Committers</title>
- <sect2>
- <title>Policy on Changing the Tier of an Architecture</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>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>
+ <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="ports">
@@ -4557,7 +4858,7 @@
merge.</para>
<para>The script assumes that you can connect to
- <literal>repo.FreeBSD.org</literal> with
+ <literal>repo.freebsd.org</literal> with
<application>SSH</application> directly, so if your
local login name is different than your &os; cluster
account, you need a few lines in your
@@ -4811,12 +5112,12 @@
<answer>
<para>The packages are built multiple times each week. If
a port fails, the maintainer will receive an email from
- <literal>pkg-fallout@FreeBSD.org</literal>.</para>
+ <literal>pkg-fallout@freebsd.org</literal>.</para>
<para>Reports for all the package builds (official,
experimental, and non-regression) are aggregated at
<link
- xlink:href="https://pkg-status.freebsd.org/">pkg-status.FreeBSD.org</link>.</para>
+ xlink:href="http://pkg-status.freebsd.org/">pkg-status.freebsd.org</link>.</para>
</answer>
</qandaentry>
@@ -4894,7 +5195,7 @@
<procedure>
<step>
<para>Go to the <link
- xlink:href="https://bugs.freebsd.org/submit">Bugzilla
+ xlink:href="http://bugs.freebsd.org/submit">Bugzilla
new <acronym>PR</acronym> page</link>.</para>
</step>
@@ -4941,52 +5242,6 @@
</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. 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>
@@ -5004,7 +5259,7 @@
<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;
+ <link xlink:href="http://www.freebsd.org/privacy.html">&os;
Privacy Policy</link>.</para>
<para>&ga; access is <emphasis>not</emphasis> arbitrarily
@@ -5102,19 +5357,19 @@
<qandaentry>
<question>
<para>How do I access <systemitem
- class="fqdomainname">people.FreeBSD.org</systemitem> to
+ 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
+ class="fqdomainname">people.freebsd.org</systemitem> is
the same as <systemitem
- class="fqdomainname">freefall.FreeBSD.org</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>
+ xlink:href="http://people.freebsd.org/">http://people.freebsd.org/</uri>.</para>
</answer>
</qandaentry>
@@ -5127,72 +5382,10 @@
<para>The mailing lists are archived under
<filename>/local/mail</filename> on <systemitem
class="fqdomainname"
- >freefall.FreeBSD.org</systemitem>.</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>
+ >freefall.freebsd.org</systemitem>.</para>
</answer>
</qandaentry>
</qandaset>
</sect1>
- <sect1 xml:id="benefits">
- <title>Benefits and Perks for &os; Comitters</title>
-
- <sect2 xml:id="benefits-recognition">
- <title>Recognition</title>
-
- <para>Recognition as a competent software engineer is the
- longest lasting value. In addition, getting a chance to work
- with some of the best people that every engineer would dream
- of meeting is a great perk!</para>
- </sect2>
-
- <sect2 xml:id="benefits-freebsdmall">
- <title>FreeBSD Mall</title>
-
- <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>.</para>
- </sect2>
-
- <sect2 xml:id="benefits-irc">
- <title><acronym>IRC</acronym></title>
-
- <para>In addition, 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.irc.email; with your requested hostmask and NickServ
- account name.</para>
- </sect2>
-
- <sect2 xml:id="benefits-gandi">
- <title><systemitem
- class="domainname">Gandi.net</systemitem></title>
-
- <para>Gandi provides website hosting, cloud computing, domain
- registration, and X.509 certificate services.</para>
-
- <para>Gandi offers an E-rate discount to all &os; developers.
- Send mail to <email>non-profit@gandi.net</email> using your
- <literal>@freebsd.org</literal> mail address, and indicate
- your Gandi handle.</para>
- </sect2>
- </sect1>
</article>

File Metadata

Mime Type
text/plain
Expires
Mon, Nov 2, 6:27 PM (14 h, 39 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
41305113
Default Alt Text
D9981.1793644076.diff (331 KB)

Event Timeline