Merge pull request #1110 from jimklimov/fix-whitespace

Replace docs references to defunct Travis CI with new NUT CI farm

docs/developers.txt

@@ -143,24 +143,31 @@ function do_stuff(void)
 At this point NUT is expected to work correctly when built with a C99
 (or GNU99 on Linux) or newer standard.
 
-See the `.travis.yml` file in project sources for detailed matrix of
-`CFLAGS` and compiler versions currently known to work or to not (yet)
-work on operating systems available to that CI solution.
-
 The NUT codebase may build in a mode without warnings made fatal on C89
 (GNU89), but the emitted warnings indicate that those binaries may crash.
 If somebody in the community requires to build and run NUT on systems
 that old, pull requests to fix the offending coding issues are welcome.
 
-The NUT project on GitHub has integration with Travis CI to test a large
-set of compiler and option combinations, covering different versions of
-gcc and clang, C standards, and requiring to pass builds at least in a
-mode without warnings (and checking the other cases where any warnings
-are made fatal).
+Continuous Integration and Automated Builds
+-------------------------------------------
+
+To ease and automate the build scenarios which were deemed important for
+quality assurance and non-regression checks of NUT, several solutions
+were introduced over time.
+
+ci_build.sh
+^^^^^^^^^^^
+
+This script was originally introduced (following ZeroMQ/ZProject example)
+to automate CI builds, by automating certain scenarios driven by exported
+environment variables to set particular `configure` options and `make`
+some targets (chosen by the `BUILD_TYPE` envvar). It can also be used
+locally to avoid much typing to re-run those scenarios during development.
 
 Developers can directly use the scripts involved in CI builds to fix
 existing code on their workstations or to ensure support for new
-compilers and C standard revisions, e.g. save a local file like this:
+compilers and C standard revisions, e.g. save a local file like this
+to call the common script with pre-sets:
 
 	$ cat _fightwarn-gcc10-gnu17.sh
 	#!/bin/sh
@@ -198,7 +205,7 @@ for their build, e.g.:
 As a rule of thumb, new contributions must not emit any warnings when
 built in GNU99 mode with a `minimal` "difficulty" level of warnings.
 Technically they must survive the part of test matrix across the several
-platforms tested by Travis CI and marked in project settings as required
+platforms tested by NUT CI and marked in project settings as required
 to pass, to be accepted for a pull request merge.
 
 Developers aiming to post successful pull requests to improve NUT can
@@ -211,12 +218,57 @@ specification revisions, might all complain about different issues --
 and catching this in as diverse range of set-ups as possible is why we
 have CI tests.
 
-It can be beneficial for serial developers to set up a local BuildBot
-or a Jenkins instance with a matrix test job, to test their local git
-repository branches with whatever systems they have available.
+It can be beneficial for serial developers to set up a local BuildBot,
+Travis or a Jenkins instance with a matrix test job, to test their local
+git repository branches with whatever systems they have available.
 
 * https://github.com/networkupstools/nut/issues/823
 
+Jenkins CI
+^^^^^^^^^^
+
+Since mid-2021, the NUT CI farm is implemented by several virtual servers
+courteously provided by FossHost. They run various operating systems as
+build agents, and a Jenkins instance to orchestrate the builds of NUT
+branches and pull requests on those agents.
+
+This is driven by `Jenkinsfile-dynamatrix` and a Jenkins Shared Library called
+link:https://github.com/networkupstools/jenkins-dynamatrix[jenkins-dynamatrix]
+which prepares a matrix of builds across as many operating systems,
+bitnesses/architectures, compilers, make programs and C/C++ revisions
+as it can -- based on the population of currently available build agents
+and capabilities which they expose as agent labels.
+
+This hopefully means that people interested in NUT can contribute to the
+build farm (and ensure NUT is and remains compatible with their platform)
+by running a Jenkins Swarm agent with certain labels, which would dial
+into https://ci.networkupstools.org/ controller. Please contact the NUT
+maintainer if you want to participate in this manner.
+
+Some further details about the NUT CI farm workers are available in
+link:config-prereqs.txt and link:ci-farm-lxc-setup.txt documents.
+
+Travis CI
+^^^^^^^^^
+
+See the `.travis.yml` file in project sources for a detailed list of third
+party dependencies and a large matrix of `CFLAGS` and compiler versions
+last known to work or to not (yet) work on operating systems available
+to that CI solution.
+
+NOTE: The cloud Travis CI offering became effectively defunct for
+open-source projects in mid-2021, so the `.travis.yml` file in NUT
+codebase is not actively maintained.
++
+Local private deployments of Travis CI are possible, so if anybody does
+use it and has updated markup to share, they are welcome to post PRs.
+
+The NUT project on GitHub has integration with Travis CI to test a large
+set of compiler and option combinations, covering different versions of
+gcc and clang, C standards, and requiring to pass builds at least in a
+mode without warnings (and checking the other cases where any warnings
+are made fatal).
+
 Pre-set warning options
 ~~~~~~~~~~~~~~~~~~~~~~~
 

docs/nut-qa.txt

@@ -66,11 +66,20 @@ trees are reported on the link:http://lists.alioth.debian.org/mailman/listinfo/n
 mailing list.
 ////////////////////////////////////////////////////////////////////////////////
 
-- link:http://buildbot.networkupstools.org/public/nut/[Buildbot] and
-link:https://travis-ci.org/networkupstools/nut/builds[Travis CI] to automate the
-compile/test cycle. Any build failure is caught early, and fixed quickly. Also
-we get to see if incoming pull requests (as well as Git branch HEADs) do not have
-code (or recipe) that is instantly faulty and can not build on even one platform.
+- link:http://buildbot.networkupstools.org/public/nut/[Buildbot]
+  and the new dedicated Jenkins incarnation of the NUT CI Farm with "legacy UI"
+  for link:https://ci.networkupstools.org/job/nut/job/nut/job/master/[main branch]
+  and link:https://ci.networkupstools.org/job/nut/job/nut/view/change-requests/[PRs],
+  also accessible at the slower but slicker-looking Blue Ocean user interface for
+  link:https://ci.networkupstools.org/blue/organizations/jenkins/nut%2Fnut/activity/[activity],
+  link:https://ci.networkupstools.org/blue/organizations/jenkins/nut%2Fnut/branches/[branches]
+  and link:https://ci.networkupstools.org/blue/organizations/jenkins/nut%2Fnut/pr/[PRs],
+  are all used to automate the compile/test cycle, using numerous platforms,
+  target distributions, C/C++ revisions, compiler toolkits and make program
+  implementations. Any build failure is caught early, and fixed quickly.
+  Also we get to see if incoming pull requests (as well as Git branch HEADs)
+  do not have code (or recipe) that is instantly faulty and can not build on
+  one of the platforms we track even with relaxed warnings.
 
 ////////////////////////////////////////////////////////////////////////////////
  reported through the

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 2731 utf-8
+personal_ws-1.1 en 2740 utf-8
 AAS
 ACFAIL
 ACFREQ
@@ -341,6 +341,7 @@ Filipozzi
 Fiskars
 FlossMetrics
 Forza
+FossHost
 Frama
 FreeBSD
 FreeDesktop
@@ -460,8 +461,8 @@ InvMin
 Invensys
 InverterV
 Invter
-Ioannou
 IoT
+Ioannou
 JAWAN
 JBus
 JKL
@@ -474,6 +475,7 @@ Jasuny
 JavaScript
 Javadoc
 Javascript
+Jenkinsfile
 Joon
 Jumpered
 KNutClient
@@ -774,6 +776,7 @@ PPDn
 PPDnnn
 PPP
 PPPPPPPPPP
+PRs
 PSA
 PSD
 PSFn
@@ -1126,6 +1129,7 @@ UB
 UBD
 UBR
 UDP
+UI
 UID
 UIDA
 UINT
@@ -1245,10 +1249,12 @@ Yoyodyne
 Yukai
 Yunto
 ZFS
+ZProject
 ZZZZZZZZ
 Zaika
 Zampieri
 Zawadzki
+ZeroMQ
 abcd
 abuild
 acVoltsIn
@@ -1397,6 +1403,7 @@ binfmt
 binutils
 bitmapped
 bitness
+bitnesses
 bitwise
 bn
 boolean
@@ -1614,6 +1621,7 @@ dummypass
 dummyups
 dumpxml
 dv
+dynamatrix
 ePDU
 ePDUs
 eaton
@@ -1634,6 +1642,7 @@ energizerups
 energysave
 english
 enum
+envvar
 ep
 epdu
 epodebounce