Date: Thu, 25 Feb 2016 20:43:25 +0000 (UTC) From: Jason Helfman <jgh@FreeBSD.org> To: src-committers@freebsd.org, svn-src-user@freebsd.org Subject: svn commit: r296065 - user/jgh/committers-guide Message-ID: <201602252043.u1PKhPL6079759@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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@example.com</replaceable></userinput> +Comment: +You selected this USER-ID: + "<replaceable>Chucky Daemon <notreal@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@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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201602252043.u1PKhPL6079759>