Page MenuHomeFreeBSD
Files F171811159

D9981.id26192.diff
No OneTemporary
Actions

D9981.id26192.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, Sep 14, 5:32 PM (6 h, 31 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
38918686
Default Alt Text
D9981.id26192.diff (331 KB)

Event Timeline