Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 15 Jul 2012 19:31:38 +0000 (UTC)
From:      Beat Gaetzi <beat@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r39217 - head/en_US.ISO8859-1/articles/committers-guide
Message-ID:  <201207151931.q6FJVcMm067877@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: beat (ports committer)
Date: Sun Jul 15 19:31:37 2012
New Revision: 39217
URL: http://svn.freebsd.org/changeset/doc/39217

Log:
  - Remove CVS chapter as ports has switched to Subversion too
  - Add ports specific information to the Subversion primer
  
  PR:		docs/169772
  Submitted by:	myself, modified by gjb
  Approved by:	gjb

Modified:
  head/en_US.ISO8859-1/articles/committers-guide/article.sgml

Modified: head/en_US.ISO8859-1/articles/committers-guide/article.sgml
==============================================================================
--- head/en_US.ISO8859-1/articles/committers-guide/article.sgml	Sun Jul 15 19:27:17 2012	(r39216)
+++ head/en_US.ISO8859-1/articles/committers-guide/article.sgml	Sun Jul 15 19:31:37 2012	(r39217)
@@ -95,11 +95,12 @@
 	  </row>
 
 	  <row>
-	    <entry><emphasis><literal>ports/</literal> CVS Root</emphasis></entry>
+	    <entry><emphasis><literal>ports/</literal> Subversion
+		Root</emphasis></entry>
 	    <entry>
-	      <hostid
-		  role="fqdn">pcvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/pcvs</filename>
-	      (see also <xref linkend="vcs.operations">).</entry>
+	      <literal>svn+ssh://</literal><hostid
+		role="fqdn">svn.FreeBSD.org</hostid><filename>/ports</filename>
+	      (see also <xref linkend="subversion-primer">).</entry>
 	  </row>
 
 	  <row>
@@ -264,827 +265,21 @@
 
   </sect1>
 
-  <sect1 id="vcs.operations">
-    <title>Version Control System Operations</title>
+  <sect1 id="subversion-primer">
+    <title>Subversion Primer</title>
 
     <para>It is assumed that you are already familiar with the basic
       operation of the version control systems in use.  Traditionally
       this was CVS.  Subversion is used for the <literal>src</literal>
-      tree as of May 2008 and the <literal>doc/www</literal> tree as
-      of May 2012.  Subversion is covered in <xref
-	linkend="subversion-primer">.</para>
-
-    <para>The &a.cvsadm; are the <quote>owners</quote> of the
-      repository and are responsible for direct modification of it for
-      the purposes of cleanup or fixing some unfortunate abuse of the
-      version control system by a committer.  Should you cause some
-      repository accident, say a bad import or a bad tag creation,
-      mail the responsible part of &a.cvsadm;, as stated in the table
-      below, (or call one of them) and report the problem.  For very
-      important issues affecting the entire tree&mdash;not just a
-      specific area&mdash;you can contact the &a.cvsadm;.  Please do
-      <emphasis>not</emphasis> contact the &a.cvsadm; for repocopies
-      or other things that the more specific teams can handle.</para>
-
-    <para><anchor id="repomeisters">The only ones able to directly
-      fiddle the repository bits on the repository hosts are the
-      repomeisters.  To enforce this, there are no login shells
-      available on the repository machines, except to the
-      repomeisters.</para>
-
-    <note>
-      <para>Depending on the affected area of the repository, you
-	should send your request for a repocopy to one of the
-	following email addresses.  Email sent to these addresses will
-	be forwarded to the appropriate repomeisters.</para>
-
-      <itemizedlist>
-	<listitem><para>pcvs@ - regarding <filename class="directory">
-	    /home/pcvs</filename>, the ports
-	  repository</para></listitem>
-
-	<listitem><para>projcvs@ - regarding <filename
-	      class="directory"> /home/projcvs</filename>, the
-	  third party projects repository</para></listitem>
-      </itemizedlist>
-    </note>
-
-    <para>The &os; repositories are currently split into two distinct
-      parts, namely <literal>ports</literal> and
-      <literal>projects</literal>.  These are combined under a single
-      <literal>CVSROOT</literal> when distributed via
-      <application>CVSup</application> for the convenience of our
-      users.  The <literal>src</literal> tree is automatically
-      exported to CVS for compatibility reasons only (e.g.,
-      <application>CVSup</application>).  The <quote>official</quote>
-      <literal>src</literal> repository is not stored in
-      <application>CVS</application> but in Subversion.  The official
-      and exported trees are not necessarily equal.</para>
-
-    <para>The CVS repositories are hosted on the repository machines.
-      Currently, each of the repositories above reside on the same
-      physical machine, <hostid
-	role="hostname">ncvs.FreeBSD.org</hostid>, but to allow for
-      the possibility of placing each on a separate machine in the
-      future, there is a separate hostname for each that committers
-      should use.  Additionally, each repository is stored in a
-      separate directory.  The following table summarizes the
-      situation.</para>
-
-    <table frame="none" id="cvs-repositories-and-hosts">
-      <title>&os; CVS Repositories, Hosts and Directories</title>
-
-      <tgroup cols="3">
-	<thead>
-	  <row>
-	    <entry>Repository</entry>
-	    <entry>Host</entry>
-	    <entry>Directory</entry>
-	  </row>
-	</thead>
-
-	<tbody>
-	  <row>
-	    <entry>ports</entry>
-	    <entry>pcvs.FreeBSD.org</entry>
-	    <entry>/home/pcvs</entry>
-	  </row>
-
-	  <row>
-	    <entry>projects</entry>
-	    <entry>projcvs.FreeBSD.org</entry>
-	    <entry>/home/projcvs</entry>
-	  </row>
-	</tbody>
-      </tgroup>
-    </table>
-
-    <para>CVS operations are done remotely by setting the
-      <envar>CVSROOT</envar> environment variable to the appropriate
-      host and top-level directory (for example, <hostid
-	role="fqdn">pcvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/pcvs</filename>),
-      and doing the appropriate check-out/check-in operations.  Many
-      committers define aliases which expand to the correct
-      <application>cvs</application> invocation for the appropriate
-      repository.  For example, a &man.tcsh.1; user may add the
-      following to their <filename>.cshrc</filename> for this
-      purpose:</para>
-
-    <programlisting>alias pcvs cvs -d <replaceable>user</replaceable>@pcvs.FreeBSD.org:/home/pcvs
-alias projcvs cvs -d <replaceable>user</replaceable>@projcvs.FreeBSD.org:/home/projcvs</programlisting>
-
-    <para>This way they can do all CVS operations locally and use
-      <command><replaceable>X</replaceable>cvs commit</command> for
-      committing to the official CVS repository.
-      Refer to the &man.cvs.1; manual page for usage.</para>
-
-    <note>
-      <para>Please do <emphasis>not</emphasis> use <command>cvs
-	  checkout</command> or <command>update</command> with the
-	official repository machine set as the CVS Root for keeping
-	your source tree up to date.  Remote CVS is not optimized for
-	network distribution and requires a big work/administrative
-	overhead on the server side.  Please use our advanced
-	<command>cvsup</command> distribution method for obtaining the
-	repository bits, and only do the actual
-	<command>commit</command> operation on the repository host.
-	We provide an extensive cvsup replication network for this
-	purpose, as well as give access to
-	<hostid>cvsup-master</hostid> if you really need to stay
-	current to the latest changes.  <hostid>cvsup-master</hostid>
-	has got the horsepower to deal with this, the repository
-	master server does not.  &a.kuriyama; is in charge of
-	<hostid>cvsup-master</hostid>.</para>
-    </note>
-
-    <para>If you need to use CVS <command>add</command> and
-      <command>delete</command> operations in a manner that is
-      effectively a &man.mv.1; operation, then a repository copy is in
-      order rather than using CVS <command>add</command> and
-      <command>delete</command>.  In a repository copy, a <link
-	linkend="repomeisters">repomeister</link> will copy the
-      file(s) to their new name and/or location and let you know when
-      it is done.  The purpose of a repository copy is to preserve
-      file change history, or logs.  We in the FreeBSD Project greatly
-      value the change history that a version control system gives to
-      the project.</para>
-
-    <para>CVS reference information, tutorials, and FAQs can be found
-      at: <ulink url="http://www.cvshome.org/docs/"></ulink>.  The
-      information in <ulink
-	url="http://cvsbook.red-bean.com/cvsbook.html">Karl Fogel's
-	chapters from <quote>Open Source Development with
-	  CVS</quote></ulink> is also very useful.</para>
-
-    <para>&a.des; also supplied the following <quote>mini
-	primer</quote> for CVS.</para>
-
-    <orderedlist>
-      <listitem>
-	<para>Check out a module with the <command>co</command> or
-	  <command>checkout</command> command.</para>
-
-	<screen>&prompt.user; <userinput>cvs checkout shazam</userinput></screen>
-
-	<para>This checks out a copy of the
-	  <filename>shazam</filename> module. If there is no
-	  <filename>shazam</filename> module in the modules file, it
-	  looks for a top-level directory named
-	  <filename>shazam</filename> instead.</para>
-
-	<table frame="none">
-	  <title>Useful <command>cvs checkout</command>
-	    options</title>
-
-	  <tgroup cols=2>
-	    <tbody>
-	      <row>
-		<entry><option>-P</option></entry>
-		<entry>Do not create empty directories</entry>
-	      </row>
-
-	      <row>
-		<entry><option>-l</option></entry>
-		<entry>Check out a single level, no
-		  subdirectories</entry>
-	      </row>
-
-	      <row>
-		<entry><option>-r<replaceable>rev</replaceable></option></entry>
-		<entry>Check out revision, branch or tag
-		  <replaceable>rev</replaceable></entry>
-	      </row>
-
-	      <row>
-		<entry><option>-D<replaceable>date</replaceable></option></entry>
-		<entry>Check out the sources as they were on date
-		  <replaceable>date</replaceable></entry>
-	      </row>
-	    </tbody>
-	  </tgroup>
-	</table>
-
-	<para>Practical FreeBSD examples:</para>
-
-	<itemizedlist>
-	  <listitem>
-	    <para>Check out the <filename>Tools</filename> module,
-	      which corresponds to
-	      <filename>ports/Tools</filename>:</para>
-
-	    <screen>&prompt.user; <userinput>cvs co Tools</userinput></screen>
-
-	    <para>You now have a directory named
-	      <filename>ports/Tools</filename> with subdirectories
-	      <filename>portbuild</filename>,
-	      <filename>scripts</filename>, and
-	      <filename>CVS</filename>.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>Check out the same files, but with full path:</para>
-
-	    <screen>&prompt.user; <userinput>cvs co ports/Tools</userinput></screen>
-
-	    <para>You now have a directory named
-	      <filename>ports</filename>, with subdirectories
-	      <filename>CVS</filename> and <filename>Tools</filename>.
-	      The <filename>ports/Tools</filename> directory has
-	      subdirectories <filename>CVS</filename> and
-	      <filename>scripts</filename>, etc.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>Check out the directory <filename>Tools</filename>,
-	      but none of the subdirectories:</para>
-
-	    <screen>&prompt.user; <userinput>cvs co -l Tools</userinput></screen>
-
-	    <para>You now have a directory named
-	      <filename>Tools</filename> with just one subdirectory
-	      named <filename>CVS</filename>.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>Check out the <filename>Tools</filename> module as
-	      it was when support for &os;&nbsp;5.X was
-	      dropped:</para>
-
-	    <screen>&prompt.user; <userinput>cvs co -rRELEASE_5_EOL Tools</userinput></screen>
-
-	    <para>You will not be able to commit modifications, since
-	      <literal>RELEASE_5_EOL</literal> is a point in time, not
-	      a branch.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>Check out the <filename>Tools</filename> module as
-	      it was on March 25th, 2009:</para>
-
-	    <screen>&prompt.user; <userinput>cvs co -D'2009-03-25' Tools</userinput></screen>
-
-	    <para>You will not be able to commit modifications.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>Check out the <filename>Tools</filename> module as
-	      it was one week ago:</para>
-
-	    <screen>&prompt.user; <userinput>cvs co -D'last week' Tools</userinput></screen>
-
-	    <para>You will not be able to commit modifications.</para>
-	  </listitem>
-	</itemizedlist>
-
-	<para>Note that cvs stores metadata in subdirectories named
-	  <filename>CVS</filename>.  Similarly, Subversion stores
-	  metadata in subdirectories named
-	  <filename>.svn</filename>.</para>
-
-	<para>Arguments to <option>-D</option> and <option>-r</option>
-	  are sticky, which means cvs will remember them later, e.g.,
-	  when you do a <command>cvs update</command>.</para>
-      </listitem>
-
-      <listitem>
-	<para>Check the status of checked-out files with the
-	  <command>status</command> command.</para>
-
-	<screen>&prompt.user; <userinput>cvs status shazam</userinput></screen>
-
-	<para>This displays the status of the file
-	  <filename>shazam</filename> or of every file in the
-	  <filename>shazam</filename> directory. For every file, the
-	  status is given as one of:</para>
-
-	<informaltable frame="none" pgwide="1">
-	  <tgroup cols=2>
-	    <tbody>
-	      <row>
-		<entry>Up-to-date</entry>
-		<entry>File is up-to-date and unmodified.</entry>
-	      </row>
-
-	      <row>
-		<entry>Needs Patch</entry>
-		<entry>File is unmodified, but there is a newer
-		  revision in the repository.</entry>
-	      </row>
-
-	      <row>
-		<entry>Locally Modified</entry>
-		<entry>File is up-to-date, but modified.</entry>
-	      </row>
-
-	      <row>
-		<entry>Needs Merge</entry>
-		<entry>File is modified, and there is a newer revision
-		  in the repository.</entry>
-	      </row>
-
-	      <row>
-		<entry>File had conflicts on merge</entry>
-		<entry>There were conflicts the last time this file
-		  was updated, and they have not been resolved
-		  yet.</entry>
-	      </row>
-	    </tbody>
-	  </tgroup>
-	</informaltable>
-
-	<para>You will also see the local revision and date,
-	  the revision number of the newest applicable version
-	  (<quote>newest applicable</quote> because if you have a
-	  sticky date, tag or branch, it may not be the actual newest
-	  revision), and any sticky tags, dates or options.</para>
-      </listitem>
-
-      <listitem>
-	<para>Once you have checked something out, you can update it
-	  with the <command>update</command> command.</para>
-
-	<screen>&prompt.user; <userinput>cvs update shazam</userinput></screen>
-
-	<para>This updates the file <filename>shazam</filename> or the
-	  contents of the <filename>shazam</filename> directory to the
-	  latest version along the branch you checked out.  If you
-	  checked out a <quote>point in time</quote>, it does nothing
-	  unless the tags have moved in the repository or some other
-	  weird stuff is going on.</para>
-
-	<para>Useful options, in addition to those listed above for
-	  <command>checkout</command>:</para>
-
-	<informaltable frame="none" pgwide="1">
-	  <tgroup cols=2>
-	    <tbody>
-	      <row>
-		<entry><option>-d</option></entry>
-		<entry>Check out any additional missing
-		  directories.</entry>
-	      </row>
-
-	      <row>
-		<entry><option>-A</option></entry>
-		<entry>Update to head of main branch.</entry>
-	      </row>
-	    </tbody>
-	  </tgroup>
-	</informaltable>
-
-	<para>If you checked out a module with <option>-r</option> or
-	  <option>-D</option>, running <command>cvs update</command>
-	  with a different <option>-r</option> or <option>-D</option>
-	  argument or with <option>-A</option> will select a new
-	  branch, revision or date. The <option>-A</option> option
-	  clears all sticky tags, dates or revisions whereas
-	  <option>-r</option> and <option>-D</option> set new
-	  ones.</para>
-
-	<para>Theoretically, specifying <literal>HEAD</literal> as the
-	  argument to <option>-r</option> will give you the same
-	  result as <option>-A</option>, but that is just
-	  theory.</para>
-
-	<para>The <option>-d</option> option is useful if:</para>
-
-	<itemizedlist>
-	  <listitem>
-	    <para>somebody has added subdirectories to the module
-	      you have checked out after you checked it out.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>you checked out with <option>-l</option>, and later
-	      change your mind and want to check out the
-	      subdirectories as well.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>you deleted some subdirectories and want to check
-	      them all back out.</para>
-	  </listitem>
-	</itemizedlist>
-
-	<para><emphasis>Watch the output of the <command>cvs
-	      update</command> with care.</emphasis> The letter in
-	  front of each filename indicates what was done with
-	  it:</para>
-
-	<informaltable frame="none" pgwide="1">
-	  <tgroup cols=2>
-	    <tbody>
-	      <row>
-		<entry><literal>U</literal></entry>
-		<entry>The file was updated without trouble.</entry>
-	      </row>
-
-	      <row>
-		<entry><literal>P</literal></entry>
-		<entry>The file was updated without trouble (you will
-		  only see this when working against a remote
-		  repository).</entry>
-	      </row>
-
-	      <row>
-		<entry><literal>M</literal></entry>
-		<entry>The file had been modified, and was merged
-		  without conflicts.</entry>
-	      </row>
-
-	      <row>
-		<entry><literal>C</literal></entry>
-		<entry>The file had been modified, and was merged with
-		  conflicts.</entry>
-	      </row>
-	    </tbody>
-	  </tgroup>
-	</informaltable>
-
-	<para>Merging is what happens if you check out a copy of some
-	  file, modify it, then someone else commits a change, and you
-	  run <command>cvs update</command>. CVS notices that you have
-	  made local changes, and tries to merge your changes with the
-	  changes between the version you originally checked out and
-	  the one you updated to. If the changes are to separate
-	  portions of the file, it will almost always work fine
-	  (though the result might not be syntactically or
-	  semantically correct).</para>
-
-	<para>CVS will print an <literal>M</literal> in front of every
-	  locally modified file even if there is no newer version in
-	  the repository, so <command>cvs update</command> is handy
-	  for getting a summary of what you have changed
-	  locally.</para>
-
-	<para>If you get a <literal>C</literal>, then your changes
-	  conflicted with the changes in the repository (the changes
-	  were to the same lines, or neighboring lines, or you changed
-	  the local file so much that <command>cvs</command> can not
-	  figure out how to apply the repository's changes). You will
-	  have to go through the file manually and resolve the
-	  conflicts; they will be marked with rows of
-	  <literal>&lt;</literal>, <literal>=</literal> and
-	  <literal>&gt;</literal> signs. For every conflict, there
-	  will be a marker line with seven <literal>&lt;</literal>
-	  signs and the name of the file, followed by a chunk of what
-	  your local file contained, followed by a separator line with
-	  seven <literal>=</literal> signs, followed by the
-	  corresponding chunk in the repository version, followed by a
-	  marker line with seven <literal>&gt;</literal> signs and the
-	  revision number you updated to.</para>
-      </listitem>
-
-      <listitem>
-	<para>View differences between the local version and the
-	  repository version with the <command>diff</command>
-	  command.</para>
-
-	<screen>&prompt.user; <userinput>cvs diff shazam</userinput></screen>
-
-	<para>shows you every modification you have made to the
-	  <filename>shazam</filename> file or module.</para>
-
-	<table frame="none">
-	  <title>Useful <command>cvs diff</command> options</title>
-
-	  <tgroup cols=2>
-	    <tbody>
-	      <row>
-		<entry><option>-u</option></entry>
-		<entry>Uses the unified diff format.</entry>
-	      </row>
-
-	      <row>
-		<entry><option>-c</option></entry>
-		<entry>Uses the context diff format.</entry>
-	      </row>
-
-	      <row>
-		<entry><option>-N</option></entry>
-		<entry>Shows missing or added files.</entry>
-	      </row>
-	    </tbody>
-	  </tgroup>
-	</table>
-
-	<para>You always want to use <option>-u</option>, since
-	  unified diffs are much easier to read than almost any other
-	  diff format (in some circumstances, context diffs generated
-	  with the <option>-c</option> option may be better, but they
-	  are much bulkier). A unified diff consists of a series of
-	  hunks. Each hunk begins with a line that starts with two
-	  <literal>@</literal> signs and specifies where in the file
-	  the differences are and how many lines they span. This is
-	  followed by a number of lines; some (preceded by a blank)
-	  are context; some (preceded by a <literal>-</literal> sign)
-	  are outtakes and some (preceded by a <literal>+</literal>)
-	  are additions.</para>
-
-	<para>You can also diff against a different version than the
-	  one you checked out by specifying a version with
-	  <option>-r</option> or <option>-D</option> as in
-	  <command>checkout</command> or <command>update</command>, or
-	  even view the diffs between two arbitrary versions (without
-	  regard for what you have locally) by specifying
-	  <emphasis>two</emphasis> versions with <option>-r</option>
-	  or <option>-D</option>.</para>
-      </listitem>
-
-      <listitem>
-	<para>View log entries with the <command>log</command>
-	  command.</para>
-
-	<screen>&prompt.user; <userinput>cvs log shazam</userinput></screen>
-
-	<para>If <filename>shazam</filename> is a file, this will
-	  print a <emphasis>header</emphasis> with information about
-	  this file, such as where in the repository this file is
-	  stored, which revision is the <literal>HEAD</literal> for
-	  this file, what branches this file is in, and any tags that
-	  are valid for this file.  Then, for each revision of this
-	  file, a log message is printed.  This includes the date and
-	  time of the commit, who did the commit, how many lines were
-	  added and/or deleted, and finally the log message that the
-	  committer who did the change wrote.</para>
-
-	<para>If <filename>shazam</filename> is a directory, then the
-	  log information described above is printed for each file in
-	  the directory in turn.  Unless you give the
-	  <option>-l</option> to <command>log</command>, the log for
-	  all subdirectories of <filename>shazam</filename> is printed
-	  too, in a recursive manner.</para>
-
-	<para>Use the <command>log</command> command to view the
-	  history of one or more files, as it is stored in the CVS
-	  repository.  You can even use it to view the log message of
-	  a specific revision, if you add the
-	  <option>-r<replaceable>rev</replaceable></option> to the
-	  <command>log</command> command:</para>
-
-	<screen>&prompt.user; <userinput>cvs log -r1.2 shazam</userinput></screen>
-
-	<para>This will print only the log message for revision
-	  <literal>1.2</literal> of file <filename>shazam</filename>
-	  if it is a file, or the log message for revision
-	  <literal>1.2</literal> of each file under
-	  <filename>shazam</filename> if it is a directory.</para>
-      </listitem>
-
-      <listitem>
-	<para>See who did what with the <command>annotate</command>
-	  command.  This command shows you each line of the specified
-	  file or files, along with which user most recently changed
-	  that line.</para>
-
-	<screen>&prompt.user; <userinput>cvs annotate shazam</userinput></screen>
-      </listitem>
-
-      <listitem>
-	<para>Add new files with the <command>add</command>
-	  command.</para>
-
-	<para>Create the file, <command>cvs add</command> it, then
-	  <command>cvs commit</command> it.</para>
-
-	<para>Similarly, you can add new directories by creating them
-	  and then <command>cvs add</command>ing them. Note that you
-	  do not need to commit directories.</para>
-      </listitem>
-
-      <listitem>
-	<para>Remove obsolete files with the <command>remove</command>
-	  command.</para>
-
-	<para>Remove the file, then <command>cvs rm</command> it, then
-	  <command>cvs commit</command> it.</para>
-      </listitem>
-
-      <listitem>
-	<para>Commit with the <command>commit</command> or
-	  <command>checkin</command> command.</para>
-
-	<table frame="none">
-	  <title>Useful <command>cvs commit</command> options</title>
-
-	  <tgroup cols=2>
-	    <tbody>
-	      <row>
-		<entry><option>-f</option></entry>
-		<entry>Force a commit of an unmodified file.</entry>
-	      </row>
-
-	      <row>
-		<entry><option>-m<replaceable>msg</replaceable></option></entry>
-		<entry>Specify a commit message on the command line
-		  rather than invoking an editor.</entry>
-	      </row>
-	    </tbody>
-	  </tgroup>
-	</table>
-
-	<para>The following are some Subversion examples related to
-	  the src repository.  More (in-depth) information can be
-	  found in the Subversion Primer at <xref
-	    linkend="subversion-primer"> and <ulink
-	     url="http://wiki.freebsd.org/SubversionMissing">List of
-	   things missing in Subversion when compared to CVS</ulink>.
-	  The notes at <ulink
-	    url="http://people.freebsd.org/~peter/svn_notes.txt"></ulink>;
-	  might also be useful.  Subversion is also described in-depth
-	  in <ulink url="http://svnbook-red-bean.com/">Version Control
-	    with Subversion</ulink>.</para>
-
-	<itemizedlist>
-	  <listitem>
-	    <para>Check out the <literal>head</literal> branch:</para>
-
-	    <screen>&prompt.user; <userinput>svn co svn+ssh://svn.freebsd.org/base/head /usr/src</userinput></screen>
-	  </listitem>
-	</itemizedlist>
-
-	<para>Good commit messages are important. They tell others why
-	  you did the changes you did, not just right here and now,
-	  but months or years from now when someone wonders why some
-	  seemingly illogical or inefficient piece of code sneaked
-	  into your source file. It is also an invaluable aid to
-	  deciding which changes to MFC and which not to MFC.</para>
-
-	<para>Commit messages should be clear, concise and provide
-	  a reasonable summary to give an indication of what was
-	  changed and why.</para>
-
-	<para>Commit messages should provide enough information to
-	  enable a third party to decide if the change is relevant to
-	  them and if they need to read the change itself.</para>
-
-	<para>Avoid committing several unrelated changes in one go. It
-	  makes merging difficult, and also makes it harder to
-	  determine which change is the culprit if a bug crops
-	  up.</para>
-
-	<para>Avoid committing style or whitespace fixes and
-	  functionality fixes in one go. It makes merging difficult,
-	  and also makes it harder to understand just what functional
-	  changes were made.  In the case of documentation files, it
-	  can make the job of the translation teams more complicated,
-	  as it becomes difficult for them to determine exactly what
-	  content changes need to be translated.</para>
-
-	<para>Avoid committing changes to multiple files in one go
-	  with a generic, vague message. Instead, commit each file (or
-	  small, related groups of files) with tailored commit
-	  messages.</para>
-
-	<para>Before committing, <emphasis>always</emphasis>:</para>
-
-	<itemizedlist>
-	  <listitem>
-	    <para>verify which branch you are committing to, using
-	      <command>svn status</command>.  This is only needed for
-	      the src tree, as the other trees are not branched.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>review your diffs, using the diff command of the
-	      version control system.</para>
-	  </listitem>
-	</itemizedlist>
-
-	<para>Also, ALWAYS specify which files to commit explicitly on
-	  the command line, so you do not accidentally commit other
-	  files than the ones you intended &mdash; a commit operation
-	  without any arguments usually will commit every modification
-	  in your current working directory and every
-	  subdirectory.</para>
-      </listitem>
-    </orderedlist>
-
-    <para>Additional tips and tricks:</para>
-
-    <orderedlist>
-      <listitem>
-
-	<para>You can place commonly used options in your
-	  <filename>~/.cvsrc</filename>, like this:</para>
-
-	<programlisting>cvs -z3
-diff -Nu
-update -Pd
-checkout -P</programlisting>
-
-	<para>This example says:</para>
-
-	<itemizedlist>
-	  <listitem>
-	    <para>always use compression level 3 when talking to a
-	      remote server. This is a life-saver when working over a
-	      slow connection.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>always use the <option>-N</option> (show added or
-	      removed files) and <option>-u</option> (unified diff
-	      format) options to &man.diff.1;.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>always use the <option>-P</option> (prune empty
-	      directories) and <option>-d</option> (check out new
-	      directories) options when updating.</para>
-	  </listitem>
-
-	  <listitem>
-	    <para>always use the <option>-P</option> (prune empty
-	      directories) option when checking out.</para>
-	  </listitem>
-	</itemizedlist>
-      </listitem>
-
-      <listitem>
-	<para>Use Eivind Eklund's <command>cdiff</command> script to
-	  view unidiffs.  It is a wrapper for &man.less.1; that adds
-	  ANSI color codes to make hunk headers, outtakes and
-	  additions stand out; context and garbage are unmodified.  It
-	  also expands tabs properly (tabs often look wrong in diffs
-	  because of the extra character in front of each
-	  line).</para>
-
-	<para><filename
-	    role="package">textproc/cdiff</filename></para>
-
-	<para>Simply use it instead of &man.more.1; or
-	  &man.less.1;:</para>
-
-	<screen>&prompt.user; <userinput>cvs diff -Nu shazam | cdiff</userinput></screen>
-
-	<para>Alternatively some editors like &man.vim.1; (<filename
-	    role="package">editors/vim</filename>) have color support
-	  and when used as a pager with color syntax highlighting
-	  switched on will highlight many types of file, including
-	  diffs, patches, and CVS/RCS logs.</para>
-
-	<screen>&prompt.user; <userinput>echo "syn on" &gt;&gt; ~/.vimrc </userinput>
-&prompt.user; <userinput>cvs diff -Nu shazam | vim -</userinput>
-&prompt.user; <userinput>cvs log shazam | vim -</userinput> </screen>
-      </listitem>
-
-      <listitem>
-	<para>CVS is old, arcane, crufty and buggy, and sometimes
-	  exhibits non-deterministic behavior which some claim as
-	  proof that it is actually merely the Newtonian manifestation
-	  of a sentient transdimensional entity.  It is not humanly
-	  possible to know its every quirk inside out, so do not be
-	  afraid to ask the resident AI (&a.cvsadm;) for help.</para>
-      </listitem>
-
-      <listitem>
-	<para>Do not leave the <command>cvs commit</command> command
-	  in commit message editing mode for too long (more than
-	  2&ndash;3 minutes).  It locks the directory you are working
-	  with and will prevent other developers from committing into
-	  the same directory.  If you have to type a long commit
-	  message, type it before executing <command>cvs
-	    commit</command> and insert it into the commit message or
-	  save it in a file before committing and use the
-	  <option>-F</option> option of CVS to read the commit message
-	  from that file, i.e.,</para>
-
-	  <screen>&prompt.user; <userinput>vi logmsg</userinput>
-&prompt.user; <userinput>cvs ci -F logmsg shazam</userinput></screen>
-
-	<para>This is the fastest way of passing a commit message to
-	  CVS but you should be careful when editing the
-	  <filename>logmsg</filename> file before the commit, because
-	  CVS will not give you a chance to edit the message when you
-	  do the actual commit.</para>
-      </listitem>
-
-      <listitem>
-	<para>Speed up your CVS operation considerably by using a
-	  persistent ssh connection to the repository machine.  First,
-	  put this configuration into your
-	  <filename>~/.ssh/config</filename>:</para>
-
-	<programlisting>Host pcvs.FreeBSD.org
-      ControlPath /home/<replaceable>user</replaceable>/.ssh/cvs.cpath
-Host projcvs.FreeBSD.org
-      ControlPath /home/<replaceable>user</replaceable>/.ssh/cvs.cpath</programlisting>
-
-	<para>Now open the persistent connection to the
-	  repoman:</para>
-
-	<screen>&prompt.user; <userinput>ssh -fNM ncvs.FreeBSD.org</userinput></screen>
-
-	<para>The CVS commands should now respond faster, as they are
-	  reusing existing connection with the repository.  Note that
-	  all the hostnames are case sensitive.</para>
-      </listitem>
-    </orderedlist>
-  </sect1>
+      tree as of May 2008, the <literal>doc/www</literal> tree as of
+      May 2012 and the <literal>ports</literal> tree as of July 2012.
+      </para>
 
-  <sect1 id="subversion-primer">
-    <title>Subversion Primer</title>
+    <para><ulink url="http://wiki.freebsd.org/SubversionMissing">There
+      is a list of things missing in Subversion when compared to CVS
+      </ulink>.  The notes at <ulink
+      url="http://people.freebsd.org/~peter/svn_notes.txt"></ulink>;
+      might also be useful.</para>
 
     <sect2 id="svn-intro">
       <title>Introduction</title>
@@ -1110,6 +305,11 @@ Host projcvs.FreeBSD.org
 	  <literal>head/<replaceable>lang</replaceable>/htdocs/</literal>.</para>
       </note>
 
+      <para>The &os; <literal>ports</literal> repository switched
+	from <acronym>CVS</acronym> to Subversion on July 14th, 2012.
+	The first real <acronym>SVN</acronym> commit is
+	<emphasis>r300894</emphasis>.</para>
+
       <para>There are mechanisms in place to automatically merge
 	changes back from the Subversion repository to the
 	<acronym>CVS</acronym> one, so regular users should not notice
@@ -1182,12 +382,19 @@ Host projcvs.FreeBSD.org
 
 	<screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/doc/head /usr/doc</userinput></screen>
 
+	<para>For the <literal>ports</literal> tree, use:</para>
+
+	<screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/ports/head /usr/ports</userinput></screen>
+
 	<note>
 	  <para>Though the remaining examples in this document are
 	    written with the workflow of working with the
 	    <literal>src</literal> tree in mind, the underlying
 	    concepts are the same for working with the
-	    <literal>doc</literal> tree.</para>
+	    <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
@@ -1456,6 +663,39 @@ Host projcvs.FreeBSD.org
 	  </listitem>
 	</itemizedlist>
       </sect3>
+
+      <sect3>
+	<title>&os; Ports Tree Branches and Layout</title>
+
+	<para>In <literal>svn+ssh://svn.freebsd.org/ports</literal>,
+	  <emphasis>ports</emphasis> refers 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 id="svn-daily-use">
@@ -1609,6 +849,13 @@ Host projcvs.FreeBSD.org
 	  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 id="subversion-primer-add-remove">
@@ -1617,6 +864,9 @@ Host projcvs.FreeBSD.org
 	<note>
 	  <para>Before adding files, get a copy of <ulink
 	      url="http://people.freebsd.org/~peter/auto-props.txt">auto-props.txt</ulink>;
+	    (there is also a <ulink
+	      url="http://people.freebsd.org/~beat/cvs2svn/auto-props.txt">;
+	      ports tree specific version</ulink>)
 	    and add it to <filename>~/.subversion/config</filename>
 	    according to the instructions in the file.  If you added
 	    something before you've read this, you may use
@@ -1624,7 +874,8 @@ Host projcvs.FreeBSD.org
 	    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>
+	      help</command>.
+	    </para>
 	</note>
 
 	<para>As with <acronym>CVS</acronym>, files are added to a
@@ -2724,6 +1975,9 @@ $target - head/$source:$P,$Q,$R</screen>
       <para>In commit logs etc., <quote>rev 179872</quote> should be
 	spelled <quote>r179872</quote> as per convention.</para>
 
+      <para>Don't remove and re-add the same file in a single commit
+	as this will break the CVS exporter.</para>
+
       <para>Speeding up checkouts and minimising network traffic is
 	possible with the following recipe:</para>
 
@@ -4287,7 +3541,7 @@ $target - head/$source:$P,$Q,$R</screen>
 
 	        <procedure>
 	          <step>
-	            <para>Remove the port's files via <command>cvs remove</command>.</para>
+	            <para>Remove the port's files via <command>svn remove</command>.</para>
 	          </step>
 
 	          <step>
@@ -4329,20 +3583,20 @@ $target - head/$source:$P,$Q,$R</screen>
 	    <para>This is essentially the reverse of deleting a port.</para>
 	    <procedure>
               <step>
-	        <para>Figure out when the port was removed.  Use the ports
-		  <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/">cvsweb</ulink>;
-		  and then navigate to
-		  <replaceable>category</replaceable>/<replaceable>portname</replaceable>/<filename>Attic</filename>/ .
+	        <para>Figure out when the port was removed.  Use this
+		  <ulink url="http://people.freebsd.org/~crees/removed_ports/index.xml">list</ulink>;
+		  and then copy the last living revision of the port:
+
+		  <screen>&prompt.user; <userinput>cd /usr/ports/<replaceable>category
+		  </replaceable></userinput>
+&prompt.user; <userinput>svn cp 'svn+ssh://svn.freebsd.org/ports/<replaceable>category</replaceable>/<replaceable>portname</replaceable>/@{<replaceable>YYYY-MM-DD</replaceable>}' <replaceable>portname</replaceable>
+		  </userinput></screen>
+

*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201207151931.q6FJVcMm067877>