Attachment 126054 Details for Bug 169772 – committers-guide-ports.patch

[patch] committers-guide-ports.patch

committers-guide-ports.patch (text/plain), 41.38 KB, created by Beat Gaetzi on 2012-07-10 21:00:31 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Beat Gaetzi

Created: 2012-07-10 21:00:31 UTC

Size: 41.38 KB

patch

obsolete

>Index: en_US.ISO8859-1/articles/committers-guide/article.sgml
>===================================================================
>--- en_US.ISO8859-1/articles/committers-guide/article.sgml	(Revision 39185)
>+++ en_US.ISO8859-1/articles/committers-guide/article.sgml	(Arbeitskopie)
>@@ -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,828 +265,22 @@
> 
>   </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>
>+      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>
> 
>-    <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><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>
> 
>-    <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>
>-
>-  <sect1 id="subversion-primer">
>-    <title>Subversion Primer</title>
>-
>     <sect2 id="svn-intro">
>       <title>Introduction</title>
> 
>@@ -1110,6 +305,11 @@
> 	  <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>rxxxxxx</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 @@
> 
> 	<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 the
>+	    <xref linkend="ports"></para>
> 	</note>
> 
> 	<para>The above command will check out a
>@@ -1456,6 +663,40 @@
> 	  </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 +850,13 @@
> 	  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,14 +865,17 @@
> 	<note>
> 	  <para>Before adding files, get a copy of <ulink
> 	      url="http://people.freebsd.org/~peter/auto-props.txt">auto-props.txt</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
>-	    <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>
>+	    (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 <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>As with <acronym>CVS</acronym>, files are added to a
>@@ -2724,6 +1975,9 @@
>       <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 @@
> 
> 	        <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 @@
> 	    <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></screen>
>+		  <screen>&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>
>+
> 		  Pick a date that is before the removal but after the last true
> 		   commit.</para>
>               </step>
> 
>               <step>
>-	        <para>In the proper directory:
>-<command>cvs update -D <replaceable>datespec</replaceable></command>.</para>
>-              </step>
>-
>-              <step>
> 	        <para>Perform whatever changes are necessary to make the port
> 		  work again.  If it was deleted because the distfiles are
> 		  no longer available you will need to volunteer to host them
>@@ -4350,7 +3604,8 @@
>               </step>
> 
>               <step>
>-	        <para><command>cvs add</command> the updated files.</para>
>+	        <para><command>svn add</command> or <command>svn remove</command>
>+		  any appropriate files.</para>
>               </step>
> 
> 	      <step>
>@@ -4365,7 +3620,7 @@
> 	      </step>
> 
> 	      <step>
>-	        <para><command>cvs commit</command> these changes, preferably in
>+	        <para><command>svn commit</command> these changes, preferably in
> 		    one step.</para>
>               </step>
> 	    </procedure>
>@@ -4402,45 +3657,30 @@
> 
> 	<qandaentry>
> 	  <question>
>-	    <para>When do we <emphasis>not</emphasis> need a
>-	      repository copy?</para>
>-	  </question>
>-
>-	  <answer>
>-	    <para>When there is no history to preserve.  If a port is
>-	      added into a wrong category and is moved immediately,
>-	      it suffices to simply <command>cvs remove</command> the
>-	      old one and <command>addport</command> the new
>-	      one.</para>
>-	  </answer>
>-	</qandaentry>
>-
>-	<qandaentry>
>-	  <question>
> 	    <para>What do I need to do?</para>
> 	  </question>
> 
> 	  <answer>
>-	    <para>File a PR in <application>GNATS</application>, listing the
>-	      reasons for the repository copy request.  Assign it to
>-	      <literal>portmgr</literal> and set <varname>state</varname> to
>-	      <literal>repocopy</literal>.  In a few days,
>-	      <literal>portmgr</literal> will do
>-	      a repository copy from the old to the new location, and
>-	      reassign the PR back to you.  Once everything is done, perform the
>-	      following:</para>
>+	    <para>Unlike with CVS a repo copy can be done by a committer
>+	      itself:</para>
> 
> 	    <itemizedlist>
> 	      <listitem>
>-		<para>When a port has been repo copied:</para>
>+		<para>Doing a repo copy:</para>
> 
> 		<procedure>
> 		  <step>
>-		    <para>Do a force commit on the files of the copied port,
>-		      stating repository copy was performed.</para>
>+		    <para>First make sure that you were using an up to
>+		      date portstree and the target directory does not
>+		      exist.</para>
> 		  </step>
> 
> 		  <step>
>+		    <para>Use <command>svn move</command> or <command>svn
>+		      copy</command> to do the repo copy.</para>
>+		  </step>
>+
>+		  <step>
> 		    <para>Upgrade the copied port to the new version.
> 		      Remember to change the <makevar>LATEST_LINK</makevar>
> 		      so there are no duplicate ports with the same name.
>@@ -4477,6 +3717,11 @@
> 		      <filename>ports/MOVED</filename>, if you remove the
> 		      original port.</para>
> 		  </step>
>+
>+		  <step>
>+		    <para>Commit all changes on one commit.  A forced commit
>+		      is no longer needed with Subversion.</para>
>+		  </step>
> 		</procedure>
> 	      </listitem>
> 
>@@ -4954,7 +4199,7 @@
> 
> 	  <answer>
> 	    <para>No, <filename>INDEX</filename> is no longer stored
>-	      in the CVS repository.  The file can either be generated
>+	      in the SVN repository.  The file can either be generated
> 	      by running <command>make index</command>, or a pre-generated
> 	      version can be downloaded with <command>make
> 	      fetchindex</command>.</para>

Actions: View | Diff

Attachments on bug 169772: 126054