FreeBSD Bugzilla – Attachment 126054 Details for
Bug 169772
[PATCH] [committers-guide] Add ports svn information
Home
|
New
|
Browse
|
Search
|
[?]
|
Reports
|
Help
|
New Account
|
Log In
Remember
[x]
|
Forgot Password
Login:
[x]
[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:
committers-guide-ports.patch
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—not just a >- specific area—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; 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><</literal>, <literal>=</literal> and >- <literal>></literal> signs. For every conflict, there >- will be a marker line with seven <literal><</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>></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 — 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" >> ~/.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–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>
You cannot view the attachment while viewing its details because your browser does not support IFRAMEs.
View the attachment on a separate page
.
View Attachment As Diff
View Attachment As Raw
Actions:
View
|
Diff
Attachments on
bug 169772
: 126054