misc/49132: Guide "Obtaining the sources" chapter unclear on security/critical branch

To: misc-bug-people%netbsd.org@localhost,gnats-admin%netbsd.org@localhost,netbsd-bugs%netbsd.org@localhost
Subject: misc/49132: Guide "Obtaining the sources" chapter unclear on security/critical branch
From: jlmuir%imca-cat.org@localhost
Date: Wed, 20 Aug 2014 17:45:00 +0000 (UTC)
>Number:         49132
>Category:       misc
>Synopsis:       Guide "Obtaining the sources" chapter unclear on 
>security/critical branch
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    misc-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Aug 20 17:45:00 +0000 2014
>Originator:     J. Lewis Muir
>Release:        -current
>Organization:
>Environment:
n/a
>Description:
The NetBSD Guide chapter titled "Obtaining the sources" [1] does not document 
the security/critical branches.  It documents the stable branch but implies 
that the stable branch is the maintenance branch.  This is all confusing since 
there are actually two flavors of maintenance branches: stable and 
security/critical.

A user was recently confused and asked about how to get the stable branch on 
the netbsd-users mailing list [2].  By documenting the security/critical branch 
along with the stable branch and clarifying some of the language, the Guide can 
hopefully avoid this kind of confusion in the future.

[1] http://netbsd.org/docs/guide/en/chap-fetch.html
[2] http://mail-index.netbsd.org/netbsd-users/2014/05/13/msg014602.html
>How-To-Repeat:
n/a
>Fix:
The following patch adds instructions for fetching the security/critical branch 
sources to the "Obtaining the sources" chapter and clarifies some of the 
language about maintenance branches to hopefully make everything more clear:

Index: docs/guide/en/chap-fetch.xml
===================================================================
RCS file: /cvsroot/htdocs/docs/guide/en/chap-fetch.xml,v
retrieving revision 1.9
diff -u -r1.9 chap-fetch.xml
--- docs/guide/en/chap-fetch.xml        12 Apr 2014 23:21:46 -0000      1.9
+++ docs/guide/en/chap-fetch.xml        20 Aug 2014 17:21:13 -0000
@@ -75,12 +75,15 @@
       directories, so you can continue to update your source tree using
       &man.cvs.1;, as explained in the CVS section.</para>
 
-    <para>Note that source tarballs for maintenance branches are only
+    <para>Note that source tarballs for stable branches are only
       updated every three days.</para>
 
     <sect2 id="chap-fetch-tarball-netbsd-release">
       <title>Downloading sources for a &os; release</title>
 
+      <para>The source files to a release do not change after the release
+        has been made.</para>
+
       <para>The tarballs for the sources of a specific release are 
       available under
       
<filename>/pub/NetBSD/NetBSD-<replaceable>&lt;RELEASE-NUMBER&gt;</replaceable>/source/sets/</filename>
 
@@ -175,12 +178,40 @@
 
 <!-- ........................................................... -->
 
+<sect2 id="chap-fetch-tarball-netbsd-seccrit">
+      <title>Downloading sources for a &os; security/critical branch</title>
+
+      <para>There are no tarballs for the sources of the
+        security/critical branches.  The recommended alternative is
+        to download tarballs for the most recent security/critical
+        <emphasis>release</emphasis> (just follow the steps in
+        <xref linkend="chap-fetch-tarball-netbsd-release"/>) of the
+        security/critical <emphasis>branch</emphasis> you want, and then use
+        &man.cvs.1; to update to the security/critical branch.  For example,
+        if you want to download tarballs for the <quote>netbsd-6-1</quote>
+        security/critical branch, and the latest security/critical
+        release is <quote>6.1.4</quote>, you would download the tarballs
+        for the <quote>6.1.4</quote> release and then update to the
+        <quote>netbsd-6-1</quote> security/critical branch as follows:</para>
+
+      <screen>&uprompt; <userinput>cd /usr/src</userinput>
+&uprompt; <userinput>cvs update -r netbsd-6-1 -Pd</userinput></screen>
+
+      <para>The same applies to the <quote>xsrc</quote> module, but in
+        that case you will have to change your working directory to
+        <filename>/usr/xsrc</filename> first.</para>
+
+</sect2>
+
+<!-- ........................................................... -->
+
 <sect2 id="chap-fetch-tarball-netbsd-current">
       <title>Downloading sources for a  &os;-current development branch</title>
 
       <para>To download the &os;-current tarballs, located under
        <filename>/pub/NetBSD/NetBSD-current/tar_files/src</filename>,
-       just follow the same steps as in the previous section, but
+       just follow the same steps as in
+       <xref linkend="chap-fetch-tarball-netbsd-stable"/>, but
        using this path.</para>
 
       <para>You may also want to fetch the X Window System sources, available
@@ -203,9 +234,16 @@
 
     <para>The list of currently maintained branches is available under
       <filename role="cvsweb">src/doc/BRANCHES</filename> (see the
-      <quote>Status</quote> entry on <quote>Release branches</quote>
+      <quote>Status</quote> entry on the <quote>Release branches</quote>
       section).</para>
 
+    <note>
+      <title>Caution!</title>
+      <para>Be sure to take care in selecting the correct and desired branch
+        tag so you don't accidentally <emphasis>downgrade</emphasis> your
+        source tree.</para>
+    </note>
+
 <!-- XXX admins@ request that people don't use cvs -z, so please don't
      modify the following instructions to include -z -->
 
@@ -257,7 +295,7 @@
     <sect2 id="chap-fetch-cvs-netbsd-stable">
       <title>Fetching a &os; stable branch</title>
 
-      <para>&os; stable branches are also called <quote>Maintenance
+      <para>&os; stable branches are a flavor of <quote>Maintenance
          branches</quote>. Please consult the 
        <xref linkend="chap-fetch-term"/>.</para>
 
@@ -285,16 +323,43 @@
        that case you will have to change your working directory to
        <filename>/usr/xsrc</filename> first.</para>
 
-<note>
-  <title>Caution!</title>
-  <para>Be sure to take care in selecting the correct and desired branch tag so
-  you don't accidentally <emphasis>downgrade</emphasis> your source 
tree.</para>
-</note>
-
  </sect2>
 
 <!-- ........................................................... -->
 
+    <sect2 id="chap-fetch-cvs-netbsd-seccrit">
+      <title>Fetching a &os; security/critical branch</title>
+
+      <para>&os; security/critical branches are a flavor of
+        <quote>Maintenance branches</quote>. Please consult the <xref
+        linkend="chap-fetch-term"/>.</para>
+
+      <para>If you want to follow a security/critical branch, just pass the
+        branch name to the &man.cvs.1; <option>-r</option> option.</para>
+
+      <para>For example, if you want to fetch the most recent version of
+        <quote>netbsd-6-1</quote>, you just need to use that tag:</para>
+
+      <screen>&uprompt; <userinput>cd /usr</userinput>
+&uprompt; <userinput>cvs checkout -r netbsd-6-1 -P src</userinput></screen>
+
+      <para>And for the <quote>xsrc</quote> module:</para>
+      <screen>&uprompt; <userinput>cvs checkout -r netbsd-6-1 -P 
xsrc</userinput></screen>
+
+      <para>If you have checked out sources from a security/critical branch
+        in <filename>/usr/src</filename> and want to update them to get the
+        latest security and critical bug fixes, run:</para>
+
+      <screen>&uprompt; <userinput>cd /usr/src</userinput>
+&uprompt; <userinput>cvs update -Pd</userinput></screen>
+
+      <para>The same applies to the <quote>xsrc</quote> module, but in
+        that case you will have to change your working directory to
+        <filename>/usr/xsrc</filename> first.</para>
+    </sect2>
+
+<!-- ........................................................... -->
+
  <sect2 id="chap-fetch-cvs-netbsd-current">
       <title>Fetching the &os;-current development branch</title>
 
@@ -314,6 +379,10 @@
        <option>-A</option> flag:
        <screen>&uprompt; <userinput>cd /usr/src</userinput>
 &uprompt; <userinput>cvs update -A -Pd</userinput></screen></para>
+
+      <para>The same applies to the <quote>xsrc</quote> module, but in
+        that case you will have to change your working directory to
+        <filename>/usr/xsrc</filename> first.</para>
     </sect2>
 
 <!-- ........................................................... -->
Prev by Date: Re: kern/12534 (Processes can hang at exit-time on ttyout)
Next by Date: NetBSD Nightly Trouble Ticket Report
Previous by Thread: Re: kern/12534 (Processes can hang at exit-time on ttyout)
Next by Thread: bin/49134: cksum, add new option -q -- quiet mode
Indexes:
Home | Main Index | Thread Index | Old Index