From 05eb216817119f51c8598ecd1af1aca6585baef8 Mon Sep 17 00:00:00 2001 From: Matt Birkholz Date: Sun, 18 Feb 2018 18:15:55 -0700 Subject: [PATCH] devops: Documentation wordsmithing. Add commented out descriptions of consistency checks not yet implemented. --- src/devops/build.texi | 113 ++++++++++++++++++++++++++---------------- 1 file changed, 71 insertions(+), 42 deletions(-) diff --git a/src/devops/build.texi b/src/devops/build.texi index 530452d1a..655a92f4f 100644 --- 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 -- 2.25.1