svn commit: r296065 - user/jgh/committers-guide
Jason Helfman
jgh at FreeBSD.org
Thu Feb 25 20:43:27 UTC 2016
Author: jgh (doc,ports committer)
Date: Thu Feb 25 20:43:25 2016
New Revision: 296065
URL: https://svnweb.freebsd.org/changeset/base/296065
Log:
- add workspace for committers guide
Added:
user/jgh/committers-guide/
user/jgh/committers-guide/Makefile (contents, props changed)
user/jgh/committers-guide/article.xml (contents, props changed)
Added: user/jgh/committers-guide/Makefile
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ user/jgh/committers-guide/Makefile Thu Feb 25 20:43:25 2016 (r296065)
@@ -0,0 +1,23 @@
+#
+# $FreeBSD$
+#
+# Article: The FreeBSD Committers Guide
+
+DOC?= article
+
+FORMATS?= html
+WITH_ARTICLE_TOC?= YES
+
+INSTALL_COMPRESSED?= gz
+INSTALL_ONLY_COMPRESSED?=
+
+SRCS= article.xml
+
+IMAGES_LIB= callouts/1.png
+IMAGES_LIB+= callouts/2.png
+IMAGES_LIB+= callouts/3.png
+
+URL_RELPREFIX?= ../../../..
+DOC_PREFIX?= ${.CURDIR}/../../..
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
Added: user/jgh/committers-guide/article.xml
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ user/jgh/committers-guide/article.xml Thu Feb 25 20:43:25 2016 (r296065)
@@ -0,0 +1,5043 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [
+<!ENTITY ga "Google Analytics">
+]>
+
+<article xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:lang="en">
+
+ <info>
+ <title>Committer's Guide</title>
+
+ <author>
+ <orgname>The &os; Documentation Project</orgname>
+ </author>
+
+ <copyright>
+ <year>1999</year>
+ <year>2000</year>
+ <year>2001</year>
+ <year>2002</year>
+ <year>2003</year>
+ <year>2004</year>
+ <year>2005</year>
+ <year>2006</year>
+ <year>2007</year>
+ <year>2008</year>
+ <year>2009</year>
+ <year>2010</year>
+ <year>2011</year>
+ <year>2012</year>
+ <year>2013</year>
+ <year>2014</year>
+ <year>2015</year>
+ <holder>The &os; Documentation Project</holder>
+ </copyright>
+
+ <legalnotice xml:id="trademarks" role="trademarks">
+ &tm-attrib.freebsd;
+ &tm-attrib.coverity;
+ &tm-attrib.ibm;
+ &tm-attrib.intel;
+ &tm-attrib.sparc;
+ &tm-attrib.general;
+ </legalnotice>
+
+ <pubdate>$FreeBSD$</pubdate>
+
+ <releaseinfo>$FreeBSD$</releaseinfo>
+
+ <abstract>
+ <para>This document provides information for the &os;
+ committer community. All new committers should read this
+ document before they start, and existing committers are
+ strongly encouraged to review it from time to time.</para>
+
+ <para>Almost all &os; developers have commit rights to one or
+ more repositories. However, a few developers do not, and some
+ of the information here applies to them as well. (For
+ instance, some people only have rights to work with the
+ Problem Report database). Please see
+ <xref linkend="non-committers"/> for more information.</para>
+
+ <para>This document may also be of interest to members of the
+ &os; community who want to learn more about how the project
+ works.</para>
+ </abstract>
+ </info>
+
+ <sect1 xml:id="admin">
+ <title>Administrative Details</title>
+
+ <informaltable frame="none" orient="port" pgwide="1">
+ <tgroup cols="2">
+ <colspec colwidth="20*"/>
+ <colspec colwidth="80*"/>
+ <tbody>
+ <row>
+ <entry><emphasis>Login Methods</emphasis></entry>
+ <entry>&man.ssh.1;, protocol 2 only</entry>
+ </row>
+
+ <row>
+ <entry><emphasis>Main Shell Host</emphasis></entry>
+ <entry><systemitem
+ class="fqdomainname">freefall.FreeBSD.org</systemitem></entry>
+ </row>
+
+ <row>
+ <entry><emphasis><literal>src/</literal> Subversion
+ Root</emphasis></entry>
+ <entry><literal>svn+ssh://</literal><systemitem
+ class="fqdomainname">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/8</literal> (8.X-STABLE),
+ <literal>stable/9</literal> (9.X-STABLE),
+ <literal>stable/10</literal> (10.X-STABLE),
+ <literal>head</literal> (-CURRENT)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>&man.ssh.1; is required to connect to the project hosts.
+ For more information, see <xref linkend="ssh.guide"/>.</para>
+
+ <para>Useful links:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><link xlink:href="&url.base;/internal/">&os;
+ Project Internal Pages</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link
+ xlink:href="&url.base;/internal/machines.html">&os;
+ Project Hosts</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link xlink:href="&url.base;/administration.html">&os;
+ Project Administrative Groups</link></para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 xml:id="pgpkeys">
+ <title>Open<acronym>PGP</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
+ <link xlink:href="http://www.nostarch.com/pgp_ml.htm">PGP &
+ 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>
+
+ <para>Existing 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>
+
+ <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>
+
+ <programlisting>fixed-list-mode
+keyid-format 0xlong
+personal-digest-preferences SHA512 SHA384 SHA256 SHA224
+default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed
+use-agent
+verify-options show-uid-validity
+list-options show-uid-validity
+sig-notation issuer-fpr at notations.openpgp.fifthhorseman.net=%g
+cert-digest-algo SHA512</programlisting>
+ </step>
+
+ <step>
+ <para>Generate a key:</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.
+There is NO WARRANTY, to the extent permitted by law.
+
+Warning: using insecure memory!
+Please select what kind of key you want:
+ (1) RSA and RSA (default)
+ (2) DSA and Elgamal
+ (3) DSA (sign only)
+ (4) RSA (sign only)
+Your selection? <userinput>1</userinput>
+RSA keys may be between 1024 and 4096 bits long.
+What keysize do you want? (2048) <userinput>2048</userinput> <co xml:id="co-pgp-bits"/>
+Requested keysize is 2048 bits
+Please specify how long the key should be valid.
+ 0 = key does not expire
+ <n> = key expires in n days
+ <n>w = key expires in n weeks
+ <n>m = key expires in n months
+ <n>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
+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 at example.com</replaceable></userinput>
+Comment:
+You selected this USER-ID:
+ "<replaceable>Chucky Daemon <notreal at example.com></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>
+
+ <calloutlist>
+ <callout arearefs="co-pgp-bits">
+ <para>2048-bit keys with a three-year expiration provide
+ adequate protection at present (2013-12). <link
+ xlink:href="http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits"/>
+ describes the situation in more detail.</para>
+ </callout>
+
+ <callout arearefs="co-pgp-expire">
+ <para>A three year key lifespan is short enough to
+ obsolete keys weakened by advancing computer power,
+ but long enough to reduce key management
+ problems.</para>
+ </callout>
+
+ <callout arearefs="co-pgp-realname">
+ <para>Use your real name here, preferably matching that
+ shown on government-issued <acronym>ID</acronym> to
+ make it easier for others to verify your identity.
+ Text that may help others identify you can be entered
+ in the <literal>Comment</literal> section.</para>
+ </callout>
+ </calloutlist>
+
+ <para>After the email address is entered, a passphrase is
+ requested. Methods of creating a secure passphrase are
+ contentious. Rather than suggest a single way, here are
+ some links to sites that describe various methods: <link
+ xlink:href="http://world.std.com/~reinhold/diceware.html"></link>,
+ <link
+ xlink:href="http://www.iusmentis.com/security/passphrasefaq/"></link>,
+ <link xlink:href="http://xkcd.com/936/"></link>,
+ <link
+ xlink:href="http://en.wikipedia.org/wiki/Passphrase"></link>.</para>
+ </step>
+ </procedure>
+
+ <para>Protect your private key and passphrase. If either the
+ private key or passphrase may have been compromised or
+ disclosed, immediately notify
+ <email>accounts at FreeBSD.org</email> and revoke the key.</para>
+
+ <para>Committing the new key is shown in
+ <xref linkend="commit-steps"/>.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="kerberos-ldap">
+ <title>Kerberos and LDAP web Password for &os; Cluster</title>
+
+ <para>The &os; cluster requires a Kerberos password to access
+ certain services. The Kerberos password also serves as the
+ LDAP web password, since LDAP is proxying to Kerberos in the
+ cluster. Some of the services
+ which require this include:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><link
+ xlink:href="https://bugs.freebsd.org/bugzilla">Bugzilla</link></para>
+ </listitem>
+ <listitem>
+ <para><link
+ xlink:href="https://jenkins.freebsd.org">Jenkins</link></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To create a new Kerberos account in the &os; cluster, or to
+ reset a Kerberos password for an existing account using a random
+ password generator:</para>
+
+ <screen>&prompt.user; <userinput>ssh kpasswd.freebsd.org</userinput></screen>
+
+ <note>
+ <para>This must be done from a machine outside of the &os;.org
+ cluster.</para>
+ </note>
+
+ <para>A Kerberos password can also be set manually
+ by logging into <systemitem
+ class="fqdomainname">freefall.FreeBSD.org</systemitem> and
+ running:</para>
+
+ <screen>&prompt.user; <userinput>kpasswd</userinput></screen>
+
+ <note>
+ <para>Unless you have used the Kerberos-authenticated services
+ of the &os;.org cluster previously,
+ <errorname>Client unknown</errorname> will be shown. This
+ error means that the
+ <command>ssh kpasswd.freebsd.org</command> method shown above
+ must be used first to initialize your Kerberos account.</para>
+ </note>
+
+ </sect1>
+
+ <sect1 xml:id="committer.types">
+ <title>Commit Bit Types</title>
+
+ <para>The &os; repository has a number of components which, when
+ combined, support the basic operating system source,
+ documentation, third party application ports infrastructure, and
+ various maintained utilities. When &os; commit bits are
+ allocated, the areas of the tree where the bit may be used are
+ specified. Generally, the areas associated with a bit reflect
+ who authorized the allocation of the commit bit. Additional
+ areas of authority may be added at a later date: when this
+ occurs, the committer should follow normal commit bit allocation
+ procedures for that area of the tree, seeking approval from the
+ appropriate entity and possibly getting a mentor for that area
+ for some period of time.</para>
+
+ <informaltable frame="none" pgwide="1">
+ <tgroup cols="3">
+ <tbody>
+ <row>
+ <entry><emphasis>Committer Type</emphasis></entry>
+ <entry><emphasis>Responsible</emphasis></entry>
+ <entry><emphasis>Tree Components</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>src</entry>
+ <entry>core@</entry>
+ <entry>src/, doc/ subject to appropriate review</entry>
+ </row>
+
+ <row>
+ <entry>doc</entry>
+ <entry>doceng@</entry>
+ <entry>doc/, ports/, src/ documentation</entry>
+ </row>
+
+ <row>
+ <entry>ports</entry>
+ <entry>portmgr@</entry>
+ <entry>ports/</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>Commit bits allocated prior to the development of the notion
+ of areas of authority may be appropriate for use in many parts
+ of the tree. However, common sense dictates that a committer
+ who has not previously worked in an area of the tree seek review
+ prior to committing, seek approval from the appropriate
+ responsible party, and/or work with a mentor. Since the rules
+ regarding code maintenance differ by area of the tree, this is
+ as much for the benefit of the committer working in an area of
+ less familiarity as it is for others working on the tree.</para>
+
+ <para>Committers are encouraged to seek review for their work as
+ part of the normal development process, regardless of the area
+ of the tree where the work is occurring.</para>
+
+ <sect2>
+ <title>Policy for Committer Activity in Other Trees</title>
+
+ <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>
+
+ <sect1 xml:id="subversion-primer">
+ <title>Subversion Primer</title>
+
+ <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>
+
+ <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>
+
+ <para>The &os; <literal>ports</literal> repository switched
+ from <acronym>CVS</acronym> to Subversion on July 14th, 2012.
+ The first real <acronym>SVN</acronym> commit is
+ <emphasis>r300894</emphasis>.</para>
+
+ <para>Subversion can be installed from the &os; Ports
+ Collection by issuing these commands:</para>
+
+ <screen>&prompt.root; <userinput>pkg install subversion</userinput></screen>
+
+ </sect2>
+
+ <sect2 xml:id="svn-getting-started">
+ <title>Getting Started</title>
+
+ <para>There are a few ways to obtain a working copy of the tree
+ from Subversion. This section will explain them.</para>
+
+ <sect3 xml:id="svn-getting-started-direct-checkout">
+ <title>Direct Checkout</title>
+
+ <para>The first is to check out directly from the main
+ repository. For the <literal>src</literal> tree,
+ use:</para>
+
+ <screen>&prompt.user; <userinput>svn checkout svn+ssh://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>
+
+ <programlisting>Host repo.freebsd.org
+ User jarjar</programlisting>
+
+ <para>This is the simplest method, but it is hard to tell just
+ yet how much load it will place on the repository.</para>
+
+ <note>
+ <para>The <command>svn diff</command> does not require
+ access to the server as <acronym>SVN</acronym> stores a
+ reference copy of every file in the working copy. This,
+ however, means that Subversion working copies are very
+ large in size.</para>
+ </note>
+ </sect3>
+
+ <sect3 xml:id="svn-getting-started-checkout-from-a-mirror">
+ <title>Checkout from a Mirror</title>
+
+ <para>Check out a working copy from a mirror by
+ substituting the mirror's <acronym>URL</acronym> for
+ <literal>svn+ssh://repo.freebsd.org/base</literal>. This
+ can be an official mirror or a mirror maintained by using
+ <command>svnsync</command>.</para>
+
+ <para>There is a serious disadvantage to this method: every
+ time something is to be committed, a
+ <command>svn relocate</command> to the master repository has
+ to be done, remembering to <command>svn relocate</command>
+ back to the mirror after the commit. Also, since
+ <command>svn relocate</command> only works between
+ repositories that have the same UUID, some hacking of the
+ local repository's UUID has to occur before it is possible
+ to start using it.</para>
+
+ <para>The hassle of a local
+ <command>svnsync</command> mirror probably is not worth it
+ unless the network connectivity situation or other factors
+ demand it. If it is needed, see the end of this chapter for
+ information on how to set one up.</para>
+ </sect3>
+
+ <sect3 xml:id="svn-getting-started-base-layout">
+ <title><literal>RELENG_*</literal> Branches and General
+ Layout</title>
+
+ <para>In <literal>svn+ssh://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>For the base repository, HEAD refers to the -CURRENT
+ tree. For example, <filename>head/bin/ls</filename> is what
+ would go into <filename>/usr/src/bin/ls</filename> in a
+ release. Some key locations are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>/head/</emphasis> which corresponds to
+ <literal>HEAD</literal>, also known as
+ <literal>-CURRENT</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>/stable/<replaceable>n</replaceable></emphasis>
+ which corresponds to
+ <literal>RELENG_<replaceable>n</replaceable></literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>/releng/<replaceable>n.n</replaceable></emphasis>
+ which corresponds to
+ <literal>RELENG_<replaceable>n_n</replaceable></literal>.</para>
+ </listitem>
+
+ <listitem>
+ <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><emphasis>/vendor*</emphasis> is the vendor branch
+ import work area. This directory itself does not
+ contain branches, however its subdirectories do. This
+ contrasts with the <emphasis>stable</emphasis>,
+ <emphasis>releng</emphasis> and
+ <emphasis>release</emphasis> directories.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>/projects</emphasis> and
+ <emphasis>/user</emphasis> feature a branch work area,
+ like in Perforce. As above, the
+ <emphasis>/user</emphasis> directory does not contain
+ branches itself.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3 xml:id="svn-getting-started-doc-layout">
+ <title>&os; Documentation Project Branches and
+ Layout</title>
+
+ <para>In <literal>svn+ssh://repo.freebsd.org/doc</literal>,
+ <emphasis>doc</emphasis> refers to the repository root of
+ the source tree.</para>
+
+ <para>In general, most &os; Documentation Project work will be
+ done within the <filename>head/</filename> branch of the
+ documentation source tree.</para>
+
+ <para>&os; documentation is written and/or translated to
+ various languages, each in a separate
+ directory in the <filename>head/</filename>
+ branch.</para>
+
+ <para>Each translation set contains several subdirectories for
+ the various parts of the &os; Documentation Project. A few
+ noteworthy directories are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>/articles/</emphasis> contains the source
+ code for articles written by various &os;
+ contributors.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>/books/</emphasis> contains the source
+ code for the different books, such as the
+ &os; Handbook.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>/htdocs/</emphasis> contains the source
+ code for the &os; website.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3 xml:id="svn-getting-started-ports-layout">
+ <title>&os; Ports Tree Branches and Layout</title>
+
+ <para>In <literal>svn+ssh://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><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><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><emphasis>/tags/RELEASE_<replaceable>n</replaceable>_EOL</emphasis>
+ represents the end of life tag of a specific &os;
+ branch.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+ </sect2>
+
+ <sect2 xml:id="svn-daily-use">
+ <title>Daily Use</title>
+
+ <para>This section will explain how to perform common day-to-day
+ operations with Subversion.</para>
+
+ <sect3 xml:id="svn-daily-use-help">
+ <title>Help</title>
+
+ <para><acronym>SVN</acronym> has built in help documentation.
+ It can be accessed by typing the following command:</para>
+
+ <screen>&prompt.user; <userinput>svn help</userinput></screen>
+
+ <para>Additional information can be found in the
+ <link xlink:href="http://svnbook.red-bean.com/">Subversion
+ Book</link>.</para>
+ </sect3>
+
+ <sect3 xml:id="svn-daily-use-checkout">
+ <title>Checkout</title>
+
+ <para>As seen earlier, to check out the &os; head
+ branch:</para>
+
+ <screen>&prompt.user; <userinput>svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src</userinput></screen>
+
+ <para>At some point, more than just <literal>HEAD</literal>
+ will probably be useful, for instance when merging changes
+ to stable/7. Therefore, it may be useful to have a partial
+ checkout of the complete tree (a full checkout would be very
+ painful).</para>
+
+ <para>To do this, first check out the root of the
+ repository:</para>
+
+ <screen>&prompt.user; <userinput>svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base</userinput></screen>
+
+ <para>This will give <literal>base</literal> with all the
+ files it contains (at the time of writing, just
+ <filename>ROADMAP.txt</filename>) and empty subdirectories
+ for <literal>head</literal>, <literal>stable</literal>,
+ <literal>vendor</literal> and so on.</para>
+
+ <para>Expanding the working copy is possible. Just change the
+ depth of the various subdirectories:</para>
+
+ <screen>&prompt.user; <userinput>svn up --set-depth=infinity base/head</userinput>
+&prompt.user; <userinput>svn up --set-depth=immediates base/release base/releng base/stable</userinput></screen>
+
+ <para>The above command will pull down a full copy of
+ <literal>head</literal>, plus empty copies of every
+ <literal>release</literal> tag, every
+ <literal>releng</literal> branch, and every
+ <literal>stable</literal> branch.</para>
+
+ <para>If at a later date merging to
+ <literal>7-STABLE</literal> is required, expand the working
+ copy:</para>
+
+ <screen>&prompt.user; <userinput>svn up --set-depth=infinity base/stable/7</userinput></screen>
+
+ <para>Subtrees do not have to be expanded completely. For
+ instance, expanding only <literal>stable/7/sys</literal> and
+ then later expand the rest of
+ <literal>stable/7</literal>:</para>
+
+ <screen>&prompt.user; <userinput>svn up --set-depth=infinity base/stable/7/sys</userinput>
+&prompt.user; <userinput>svn up --set-depth=infinity base/stable/7</userinput></screen>
+
+ <para>Updating the tree with <command>svn update</command>
+ will only update what was previously asked for (in this
+ case, <literal>head</literal> and
+ <literal>stable/7</literal>; it will not pull down the whole
+ tree.</para>
+
+ <note>
+ <para>Decreasing the depth of a working copy is not
+ possible.</para>
+ </note>
+ </sect3>
+
+ <sect3 xml:id="svn-daily-use-anonymous-checkout">
+ <title>Anonymous Checkout</title>
+
+ <para>It is possible to anonymously check out the &os;
+ repository with Subversion. This will give access to a
+ read-only tree that can be updated, but not committed back
+ to the main repository. To do this, use the following
+ command:</para>
+
+ <screen>&prompt.user; <userinput>svn co https://svn.FreeBSD.org/base/head /usr/src</userinput></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>
+
+ <sect3 xml:id="svn-daily-use-updating-the-tree">
+ <title>Updating the Tree</title>
+
+ <para>To update a working copy to either the latest revision,
+ or a specific revision:</para>
+
+ <screen>&prompt.user; <userinput>svn update</userinput>
+&prompt.user; <userinput>svn update -<replaceable>r12345</replaceable></userinput></screen>
+ </sect3>
+
+ <sect3 xml:id="svn-daily-use-status">
+ <title>Status</title>
+
+ <para>To view the local changes that have been made to the
+ working copy:</para>
+
+ <screen>&prompt.user; <userinput>svn status</userinput></screen>
+
+ <para>To show local changes and files that are out-of-date
+ do:</para>
+
+ <screen>&prompt.user; <userinput>svn status --show-updates</userinput></screen>
+ </sect3>
+
+ <sect3 xml:id="svn-daily-use-editing-and-committing">
+ <title>Editing and Committing</title>
+
+ <para>Unlike Perforce, <acronym>SVN</acronym> does not need to
+ be told in advance about file editing.</para>
+
+ <para>To commit all changes in
+ the current directory and all subdirectories:</para>
+
+ <screen>&prompt.user; <userinput>svn commit</userinput></screen>
+
+ <para>To commit all changes in, for example,
+ <filename><replaceable>lib/libfetch/</replaceable></filename>
+ and
+ <filename><replaceable>usr/bin/fetch/</replaceable></filename>
+ in a single operation:</para>
+
+ <screen>&prompt.user; <userinput>svn commit <replaceable>lib/libfetch</replaceable> <replaceable>usr/bin/fetch</replaceable></userinput></screen>
+
+ <para>There is also a commit wrapper for the ports tree to
+ handle the properties and sanity checking your
+ changes:</para>
+
+ <screen>&prompt.user; <userinput>/usr/ports/Tools/scripts/psvn commit</userinput></screen>
+ </sect3>
+
+ <sect3 xml:id="svn-daily-use-adding-and-removing">
+ <title>Adding and Removing Files</title>
+
+ <note>
+ <para>Before adding files, get a copy of <link
+ xlink:href="http://people.freebsd.org/~peter/auto-props.txt">auto-props.txt</link>
+ (there is also a <link
+ xlink:href="http://people.freebsd.org/~beat/cvs2svn/auto-props.txt">
+ ports tree specific version</link>) and add it to
+ <filename>~/.subversion/config</filename> according to the
+ instructions in the file. If you added something before
+ reading this, use <command>svn rm --keep-local</command>
+ for just added files, fix your config file and re-add them
+ again. The initial config file is created when you first
+ run a svn command, even something as simple as
+ <command>svn help</command>.</para>
+ </note>
+
+ <para>Files are added to a
+ <acronym>SVN</acronym> repository with <command>svn
+ add</command>. To add a file named
+ <emphasis>foo</emphasis>, edit it, then:</para>
+
+ <screen>&prompt.user; <userinput>svn add <replaceable>foo</replaceable></userinput></screen>
+
+ <note>
+ <para>Most new source files should include a
+ <literal>$&os;$</literal> string near the
+ start of the file. On commit, <command>svn</command> will
+ expand the <literal>$&os;$</literal> string,
+ adding the file path, revision number, date and time of
+ commit, and the username of the committer. Files which
+ cannot be modified may be committed without the
+ <literal>$&os;$</literal> string.</para>
+ </note>
+
+ <para>Files can be removed with <command>svn
+ remove</command>:</para>
+
+ <screen>&prompt.user; <userinput>svn remove <replaceable>foo</replaceable></userinput></screen>
+
+ <para>Subversion does not require deleting the file before
+ using <command>svn rm</command>, and indeed complains if
+ that happens.</para>
+
+ <para>It is possible to add directories with
+ <command>svn add</command>:</para>
+
+ <screen>&prompt.user; <userinput>mkdir <replaceable>bar</replaceable></userinput>
+&prompt.user; <userinput>svn add <replaceable>bar</replaceable></userinput></screen>
+
+ <para>Although <command>svn mkdir</command> makes this easier
+ by combining the creation of the directory and the adding of
+ it:</para>
+
+ <screen>&prompt.user; <userinput>svn mkdir <replaceable>bar</replaceable></userinput></screen>
+
+ <para>Like files, directories are removed with
+ <command>svn rm</command>. There is no separate command
+ specifically for removing directories.</para>
+
+ <screen>&prompt.user; <userinput>svn rm <replaceable>bar</replaceable></userinput></screen>
+ </sect3>
+
+ <sect3 xml:id="svn-daily-use-copying-and-moving">
+ <title>Copying and Moving Files</title>
+
+ <para>This command creates a copy of
+ <filename>foo.c</filename> named <filename>bar.c</filename>,
+ with the new file also under version control:</para>
+
+ <screen>&prompt.user; <userinput>svn copy <replaceable>foo.c</replaceable> <replaceable>bar.c</replaceable></userinput></screen>
+
+ <para>The example above is equivalent to:</para>
+
+ <screen>&prompt.user; <userinput>cp foo.c bar.c</userinput>
+&prompt.user; <userinput>svn add bar.c</userinput></screen>
+
+ <para>To move and rename a file:</para>
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-src-user
mailing list