docs/155691: New section of Porter's Handbook; Using CVS to make patches
Chris Rees
utisoft at gmail.com
Sat Mar 19 11:10:09 UTC 2011
>Number: 155691
>Category: docs
>Synopsis: New section of Porter's Handbook; Using CVS to make patches
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Sat Mar 19 11:10:09 UTC 2011
>Closed-Date:
>Last-Modified:
>Originator: Chris Rees
>Release: FreeBSD 8.2-RELEASE i386
>Organization:
>Environment:
System: FreeBSD zeus.bayofrum.net 8.2-RELEASE FreeBSD 8.2-RELEASE #1: Sun Feb 27 22:19:51 UTC 2011 root at zeus.bayofrum.net:/usr/obj/usr/src/sys/ZEUS i386
>Description:
Ion-Mihai Tetcu has written a guide [1] to making cvs diffs of port changes. This is the first part of it, put into (I hope) an appropriate part of the Porter's Handbook.
My plan is to later merge the tips on PRs into the PR submission guide too, and perhaps link them.
[1] http://ionut.tetcu.info/FreeBSD/How-to-submit-a-diff.txt
>How-To-Repeat:
>Fix:
I've added into the Upgrading an individual port chapter a section on how to make a cvs diff (written by itetcu@, not quite sure how to acknowledge that) as well as adding a link in the introduction where using diff is mentioned.
Rendered: http://www.bayofrum.net/~crees/port.html (the callout images are missing, which is why they're the alt text (#))
- Added section How to make a cvs diff
- Added link to section where diff methods are described
PR:
Submitted by: Chris Rees (utisoft_at_gmail.com)
Original author: itetcu
--- porters-cvs-diff.diff begins here ---
Index: book.sgml
===================================================================
RCS file: /exports/cvsroot-freebsd/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.1097
diff -u -r1.1097 book.sgml
--- book.sgml 18 Feb 2011 20:57:00 -0000 1.1097
+++ book.sgml 13 Mar 2011 17:58:30 -0000
@@ -9524,8 +9524,9 @@
<screen>&prompt.user; <userinput>/usr/bin/diff something.orig something > something.diff</userinput></screen>
</informalexample>
- <para>Otherwise, you should copy the contents of the port to an entire
- different directory and use
+ <para>Otherwise, you should either use the <command>cvs diff</command>
+ method (<xref linkend="cvs-diff">) or copy the contents of the port to
+ an entire different directory and use
the result of the
recursive &man.diff.1; output
of the new and old
@@ -9595,6 +9596,127 @@
<para>Now that you have done all that, you will want to read about
how to keep up-to-date in <xref linkend="keeping-up">.</para>
+ <sect1 id="cvs-diff">
+ <title>Using CVS to make patches</title>
+
+ <para>If you can, please submit a cvs diff, they are easier to handle
+ than diffs between <quote>new and old</quote> dirs. Plus it's easier
+ for you to see what you have changed and update your diff if
+ something is modified in the Ports Collection from when you started
+ to work on it until you submit your changes or if the committer asks
+ you to fix something.</para>
+
+ <screen>&prompt.user; <userinput>cd ~/my_wrkdir</userinput> <co id="my-wrkdir">
+&prompt.user; <userinput>cvs -d R_CVSROOT co pdnsd</userinput> <co id="R-CVSROOT"> <co id="module-name">
+&prompt.user; <userinput>cd ~/my_wrkdir/pdnsd</userinput></screen>
+ <calloutlist>
+ <callout arearefs="my-wrkdir">
+ <para>This can be anywhere you want, of course; ports can be
+ built from anywhere, not only
+ <filename class="directory">/usr/ports/</filename>.</para>
+ </callout>
+
+ <callout arearefs="R-CVSROOT">
+ <para>R_CVSROOT is any public cvs server, take your pick from
+ the list in the <ulink url="&url.books.handbook">&os;
+ Handbook</ulink>.</para>
+ </callout>
+
+ <callout arearefs="module-name">
+ <para>pdnsd is the module name for the port; it is generally the
+ name of the port, with some exceptions, notably for national
+ categories (<filename role="package">german/selfhtml</filename>
+ has the module name de-selfhtml); you can either
+ look up the module name via the
+ <ulink url="&url.base;/cgi/cvsweb.cgi/ports">cvsweb
+ interface</ulink> or write the whole path, in our example
+ <filename class="directory">ports/dns/pdnsd</filename>.</para>
+ </callout>
+ </calloutlist>
+
+ <para>While in the working directory, make any changes that you
+ would usually make to the port. If you add or remove a file, use
+ <command>cvs</command> to track these changes:</para>
+
+ <screen>&prompt.user; <userinput>cvs add new_file</userinput>
+&prompt.user; <userinput>cvs rm deleted_file</userinput></screen>
+
+ <para>Make sure that you check the port using the
+ checklist in <xref linkend="porting-testing"> and
+ <xref linkend="porting-portlint">.</para>
+
+ <screen>&prompt.user; <userinput>cvs status</userinput>
+&prompt.user; <userinput>cvs update</userinput> <co id="cvs-update"></screen>
+
+ <calloutlist>
+ <callout arearefs="cvs-update">
+ <para>This will try to merge the differences between your patch
+ and current CVS; watch the output carefully. The letter in front
+ of each file name indicates what was done with it, described in
+ <xref linkend="table-cvs-up">.</para>
+ </callout>
+ </calloutlist>
+
+ <table pgwide="1" frame="none" id="table-cvs-up">
+ <title>cvs update file prefixes</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>U</entry>
+
+ <entry>The file was updated without trouble.</entry>
+ </row>
+
+ <row>
+ <entry>P</entry>
+
+ <entry>The file was updated without trouble (you will only see
+ this when working against a remote repository).</entry>
+ </row>
+
+ <row>
+ <entry>M</entry>
+
+ <entry>The file had been modified, and was merged without
+ conflicts.</entry>
+ </row>
+
+ <row>
+ <entry>C</entry>
+
+ <entry>The file had been modified, and was merged with
+ conflicts.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>If you get <literal>C</literal> as a result of
+ <literal>cvs update</literal> it means something
+ changed in the CVS and &man.cvs.1; wasn't able to merge your local
+ changes and those from CVS. It's always a good idea to inspect the
+ changes anyway, since <command>cvs</command> doesn't know anything
+ about how a port should be, so it might (and probably will) merge
+ things that don't make sense.</para>
+
+ <para>The last step is to make a unified &man.diff.1;
+ of the files against CVS:
+
+ <screen>&prompt.user; <userinput>cvs diff -uN > ../`basename ${PWD}`.diff</userinput></screen>
+
+ <note>
+ <para>It is important to use <option>-N</option> to ensure that
+ files you have removed are accounted for in the patch. The patch
+ will empty (but leave existing) any removed files when applied, so
+ remember to include these in the PR so the committer knows to
+ remove them.</para>
+ </note>
+
+ <para>Send your patch following the guidelines in
+ <xref linkend="port-upgrading">.</para>
+ </sect1>
+
<sect1 id="moved-and-updating-files">
<title>The files UPDATING and MOVED</title>
--- porters-cvs-diff.diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list