devops: Documentation wordsmithing.

Add commented out descriptions of consistency checks not yet implemented.

diff --git a/src/devops/build.texi b/src/devops/build.texi
index 530452d1ae188c0b16a1796daf0327ecdb23d54b..655a92f4f4f39d2a80df2b9770a2242d30e4dca2 100644 (file)
--- a/src/devops/build.texi
+++ b/src/devops/build.texi
@@ -3,27 +3,26 @@
 
 The goal of the devops build system is to release from a developer's
 git repository lint free source distributions with binaries for
-several different machine architectures and operating system versions.
-The binaries for each combination of architecture and operating system
-are built by a ``build host.''  Ubuntu hosts build Debian packages as
-well as the traditional binaries.  Both packages and binaries are
-installed as they are built, to test their installation and to fulfill
-build dependencies between new releases.
+several different machine architectures and operating systems.  The
+binaries for each combination of architecture and operating system are
+built by a separate ``build host.''  Ubuntu hosts build Debian
+packages as well as the traditional binaries.  Both packages and
+binaries are installed as they are built, to test their installation
+and to satisfy the build dependencies of subsequent releases.
 
 The release process begins in the developer's git repository, in a git
-clean, lint free, well tested working directory.  The developer
-creates the release by creating a tag in the git repository, then
-builds a source distribution from the tag using GNU's Autotools.  If
-the developer is sharing a project repository and download area, the
-tag is pushed and the source distribution is uploaded.  If the
-developer is working alone, the tag stays in the local git repository
-and the source distribution stays in the local build area
-(@file{devops/} in the top working directory).
-
-The @emph{build} process begins in the @emph{project} (or developer)
-git repository, possibly a bare repository on a shared server, where a
-build status report polls each build host using passwordless
-@code{ssh} to upload new releases and assess progress on builds.
+clean, lint free, well tested working directory.  A release is created
+by creating a git tag, building source distributions from that tag,
+and pushing/uploading the tag/distributions to the shared project
+repository (if not the same as the developer's repository).
+
+The @emph{build} process begins in the @emph{project} git repository,
+possibly a bare repository on a shared server, where a build status
+report polls each build host using passwordless @code{ssh}.  The
+status report automatically uploads new releases (if any) and launches
+a build (if necessary), or reports the error that has stopped the
+build on that host.  Releases are built serially, in the order that
+they were created.  No dependency checking is currently in place.
 
 @menu
 * Project Repository::
@@ -50,7 +49,7 @@ commands could be used to check out @code{pucked}, then start an
 @smallexample
 git clone git://git.savannah.gnu.org/mit-scheme.git
 cd mit-scheme/
-git remote add puck git://birchwood-abbey.net/~matt/mit-scheme.git
+git remote add puck git://birchwood-abbey.net/~puck/mit-scheme.git
 git fetch puck pucked
 git checkout puck/pucked
 # Fix, then decide to commit on a local branch named "unpucked".
@@ -68,11 +67,11 @@ The devops build system is configured by a @file{config.scm} file in
 its build area, @file{devops/} (possibly a symbolic link).  The
 @file{devops/config.scm} file is loaded into the @code{(devops)}
 package where it can find procedures to set build system variables and
-customize any part of the build processees.
+customize any part of the build processes.
 
 @deffn Procedure project-name [name]
 Returns the project name (a string) after setting it to @var{name}
-(when specified).  @var{Name} should be a lower case string without
+(when provided).  @var{Name} should be a lower case string without
 whitespace or punctuation; it is used to create file names.  Until it
 is set the project name is @code{"new-scheme"}.
 @end deffn
@@ -203,36 +202,66 @@ numbers are detected.
 
 The following checks are performed on a core Scheme source tree.
 
-The project version numbers in the documentation (@file{version.texi})
-and source (@file{runtime/version.scm}), and in
-@file{debian/changelog} should match.
+@itemize @bullet
+@item
+The project version number in the source (@file{runtime/version.scm}),
+and in @file{debian/changelog} should match.
 
+@item
 If there is a change in any file in the core source, the
-project version should have been incremented.
+project version should have incremented.
+
+@c @item
+@c The version numbers in the documentation (variables named
+@c @code{SCMVERS} in @file{doc/**/*.texinfo}) agree with
+@c @file{src/runtime/version.scm}.
 
-@c All files should contain a header with the same copyright notice and
-@c the notice should include the current year.
-@c Unless no file has changed since the last year in the notice?
+@c @item
+@c All source files should contain a header with the same copyright
+@c notice
+
+@c @item
+@c The copyright notice should include the current year (unless no
+@c file has changed since the last year in the notice?).
+@end itemize
 
 @node Plugin Lint
 @subsection Plugin Lint
 
 The following checks are performed on a plugin source tree.
 
-The plugin version numbers in the documentation (@file{version.texi})
-and source (@file{make.scm}), in @file{NEWS} and
-@file{src/configure.ac} and @file{debian/changelog} all match.
+@itemize @bullet
+@item
+The plugin version numbers in @file{configure.ac}, @file{make.scm},
+@file{NEWS}, @file{debian/changelog}, and @file{version.texi} (if any)
+all match.
 
+@item
 If there is a change in any file in the plugin source, the plugin
-version should have been incremented.
-
-@c All files should contain a header with the same copyright notice and
-@c the notice should include the current year.
-@c Unless no file has changed since the last year in the notice?
-
-@c The source includes all GNU standard files, @file{README},
-@c @file{ChangeLog}, @file{AUTHORS}, @file{COPYING} and @file{NEWS} are
-@c present in the customary format.
-
+version should have incremented.
+
+@c @item
+@c The top entries in @file{NEWS} and @file{debian/changelog} have the
+@c same version number as @file{make.scm} and the same content.
+
+@c @item
+@c The Scheme version number in the documentation (a variable named
+@c @code{SCMVERS} in a @file{@var{plugin}.texi} file if any) matches
+@c the required core version specified in @file{debian/control}.
+ 
+@c @item
+@c All source files should contain a header with the same copyright
+@c notice
+
+@c @item
+@c The copyright notice should include the current year (unless no
+@c file has changed since the last year in the notice?).
+
+@c @item
+@c The source includes all GNU standard files: @file{README},
+@c @file{ChangeLog}, @file{AUTHORS}, @file{COPYING} and @file{NEWS}.
+
+@c @item
 @c The plugin should have a manual containing a @code{@@deffn} section
 @c for every binding it exports to the global environment.
+@end itemize