02/11: doc: Augment documentation about security updates.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 09866b3962df38cc704d993ca1e6c77f1b360523
Author: Ludovic Courtès <address@hidden>
Date:   Mon Mar 28 17:56:05 2016 +0200

    doc: Augment documentation about security updates.
    
    * doc/guix.texi (Security Updates): Add paragraph on the big picture of
    security updates.  Cross-reference 'guix lint'.
    (Invoking guix lint): Add CVE URLs.
---
 doc/guix.texi |   45 +++++++++++++++++++++++++++++++++++++++------
 1 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 04b2ace..3b050a6 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4913,11 +4913,26 @@ just a version number or ``git-checkout'', without a 
declared
 @code{file-name} (@pxref{origin Reference}).
 
 @item cve
address@hidden security vulnerabilities
address@hidden CVE, Common Vulnerabilities and Exposures
 Report known vulnerabilities found in the Common Vulnerabilities and
-Exposures (CVE) database
+Exposures (CVE) databases of the current and past year
 @uref{https://nvd.nist.gov/download.cfm#CVE_FEED, published by the US
 NIST}.
 
+To view information about a particular vulnerability, visit pages such as:
+
address@hidden
address@hidden
address@hidden://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
address@hidden
address@hidden://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
address@hidden itemize
+
address@hidden
+where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
address@hidden
+
 @item formatting
 Warn about obvious source code formatting issues: trailing white space,
 use of tabulations, etc.
@@ -10450,14 +10465,32 @@ the load.  To check whether a package has a 
@code{debug} output, use
 @node Security Updates
 @section Security Updates
 
address@hidden security updates
address@hidden security vulnerabilities
+Occasionally, important security vulnerabilities are discovered in software
+packages and must be patched.  Guix developers try hard to keep track of
+known vulnerabilities and to apply fixes as soon as possible in the
address@hidden branch of Guix (we do not yet provide a ``stable'' branch
+containing only security updates.)  The @command{guix lint} tool helps
+developers find out about vulnerable versions of software packages in the
+distribution:
+
address@hidden
+$ guix lint -c cve
+gnu/packages/base.scm:652:2: glibc-2.21: probably vulnerable to CVE-2015-1781, 
CVE-2015-7547
+gnu/packages/gcc.scm:334:2: gcc-4.9.3: probably vulnerable to CVE-2015-5276
+gnu/packages/image.scm:312:2: openjpeg-2.1.0: probably vulnerable to 
CVE-2016-1923, CVE-2016-1924
address@hidden
address@hidden smallexample
+
address@hidden guix lint}, for more information.
+
 @quotation Note
-As of version @value{VERSION}, the feature described in this section is
-experimental.
+As of version @value{VERSION}, the feature described below is considered
+``beta''.
 @end quotation
 
address@hidden security updates
-Occasionally, important security vulnerabilities are discovered in core
-software packages and must be patched.  Guix follows a functional
+Guix follows a functional
 package management discipline (@pxref{Introduction}), which implies
 that, when a package is changed, @emph{every package that depends on it}
 must be rebuilt.  This can significantly slow down the deployment of