Merge branch 'PhoenixContactModbus-add-new-models' of https://github.com/RikyPlaza/nut into PhoenixContactModbus-add-new-models

Author: RikyPlaza

Jenkinsfile-dynamatrix

@@ -255,7 +255,11 @@ import org.nut.dynamatrix.*;
 
     // Imported from jenkins-dynamatrix JSL vars/autotools.groovy:
     // a workaround for the cases of curiously missing MAKE envvar...
-    dynacfgPipeline.buildPhases['distcheck'] = """( if [ x"\${MAKE-}" = x ]; then echo "WARNING: MAKE is somehow unset, defaulting!" >&2; MAKE=make; fi; eval \${CONFIG_ENVVARS} time \${MAKE} \${MAKE_OPTS} distcheck DISTCHECK_FLAGS=\${CONFIG_OPTS:+\\"\$CONFIG_OPTS\\"} )"""
+    // Note that NUT Makefile has a concept of "distcheck-ci" to
+    // cater for documentation files (pre-generated man pages) that
+    // must be present in the dist tarball, but may not be available
+    // or creatable on the build agent - in that case we fake them.
+    dynacfgPipeline.buildPhases['distcheck'] = """( if [ x"\${MAKE-}" = x ]; then echo "WARNING: MAKE is somehow unset, defaulting!" >&2; MAKE=make; fi; eval \${CONFIG_ENVVARS} time \${MAKE} \${MAKE_OPTS} distcheck-ci DISTCHECK_FLAGS=\${CONFIG_OPTS:+\\"\$CONFIG_OPTS\\"} )"""
 
     // Note: shellcheck/spellcheck/... require autotools currently
     // or need to be redefined with respective BUILD_TYPE

Makefile.am

@@ -40,7 +40,7 @@ ACLOCAL_AMFLAGS = -I m4
 # (alas sequential) target recipes. The order matters, as several subdirectories
 # depend on stuff in "common" or tools being built first!
 SUBDIRS = include common clients conf data drivers tools \
-  lib scripts server tests docs
+  lib scripts server tests docs/man docs
 
 # Note: not generated from SUBDIRS, because not all are recursive:
 SUBDIRS_ALL_RECURSIVE = \
@@ -420,24 +420,100 @@ DISTCHECK_CONFIGURE_FLAGS = ${DISTCHECK_FLAGS}		\
 # DISTCHECK_CONFIGURE_FLAGS defaults defined above in a manner
 # that is meaningful for sub-make program (gets stripped away
 # otherwise and breaks custom distchecks).
-distcheck-light:
+
+# Helper for CI runs: ensure presence of pre-built man pages
+# (even if faked where lack and can not build them), so that
+# the majority of distcheck logic can pass.
+# See also docs/man/Makefile.am
+if KNOWN_UNABLE_MANS
+if DOC_INSTALL_DISTED_MANS
+distcheck-ci: distcheck
+dist-ci: dist
+else !DOC_INSTALL_DISTED_MANS
+distcheck-ci: distcheck-fake-man
+dist-ci: dist-fake-man
+endif !DOC_INSTALL_DISTED_MANS
+else !KNOWN_UNABLE_MANS
+if WITH_MANS
+distcheck-ci: distcheck
+dist-ci: dist
+else !WITH_MANS
+if HAVE_ASCIIDOC
+distcheck-ci: distcheck
+dist-ci: dist
+else !HAVE_ASCIIDOC
+if DOC_INSTALL_DISTED_MANS
+distcheck-ci: distcheck
+dist-ci: dist
+else !DOC_INSTALL_DISTED_MANS
+distcheck-ci: distcheck-fake-man
+dist-ci: dist-fake-man
+endif !DOC_INSTALL_DISTED_MANS
+endif !HAVE_ASCIIDOC
+endif !WITH_MANS
+endif !KNOWN_UNABLE_MANS
+
+# Helper for a number of recipes below that explicitly agree to not require
+# always real man pages (but require them to dist => distcheck-something)
+# for CI or developer iterations on environments with incomplete tool kits:
+distcheck-light-DIST_ALL_PAGES:
+	@echo "Starting $@" >&2
+	+@cd "$(abs_builddir)/docs/man" && $(MAKE) $(AM_MAKEFLAGS) all
+	+@cd "$(abs_builddir)/docs/man" && $(MAKE) $(AM_MAKEFLAGS) distcheck-light-DIST_ALL_PAGES
+	@echo "Completed $@: preparation of pre-built man pages for dist tarball, possibly faked" >&2
+
+# Here we generate man pages (if absent) or fake them
+# Require other dependencies as usual distcheck does;
+# be sure to pass through caller's DISTCHECK_FLAGS (if any)
+distcheck-fake-man: distcheck-light-DIST_ALL_PAGES
+	@echo "Starting $@" >&2
+	+prefix='$${prefix}'; if test x"$(DISTCHECK_FLAGS)" = x ; then \
+		$(MAKE) $(AM_MAKEFLAGS) distcheck ; \
+	 else \
+		$(MAKE) $(AM_MAKEFLAGS) DISTCHECK_FLAGS="$(DISTCHECK_FLAGS)" distcheck ; \
+	 fi
+	@echo "Completed $@: strict distcheck, but with possibly faked pre-built man pages" >&2
+
+dist-fake-man: distcheck-light-DIST_ALL_PAGES
+	@echo "Starting $@" >&2
+	+prefix='$${prefix}'; $(MAKE) $(AM_MAKEFLAGS) dist
+	@echo "Completed $@: strict dist, but with possibly faked pre-built man pages" >&2
+
+# Here we allow to skip docs if tools are absent, so "make dist"
+# should not hiccup on lack of the page files (but MAY make them
+# if it can); be relaxed toward other dependencies.
+distcheck-light: distcheck-light-DIST_ALL_PAGES
+	@echo "Starting $@" >&2
 	+prefix='$${prefix}'; $(MAKE) $(AM_MAKEFLAGS) DISTCHECK_FLAGS="$(DISTCHECK_LIGHT_FLAGS)" distcheck
+	@echo "Completed $@: relaxed distcheck, with possibly faked pre-built man pages" >&2
 
+# Require man pages to be built (or fail trying), but not other docs;
+# be relaxed toward other dependencies.
 distcheck-light-man:
+	@echo "Starting $@" >&2
 	+prefix='$${prefix}'; $(MAKE) $(AM_MAKEFLAGS) DISTCHECK_FLAGS="$(DISTCHECK_LIGHT_MAN_FLAGS)" distcheck
+	@echo "Completed $@: relaxed distcheck, with real man pages" >&2
 
 if HAVE_VALGRIND
 # Make the check in current build, if possible
 memcheck:
+	@echo "Starting $@" >&2
 	@echo "See also scripts/valgrind in NUT sources for a helper tool"
 	+@cd $(builddir)/tests && $(MAKE) $(AM_MAKEFLAGS) -s $@
 
 # Make a distcheck (and check in particular) with enabled valgrind and debug info
+# Here we skip docs so "make dist" should not hiccup on lack of the page files
+# (nor try to make them); not using simple distcheck-light-DIST_ALL_PAGES step
+# due to custom logic!
 distcheck-valgrind:
+	@echo "Starting $@" >&2
 	@echo "See also scripts/valgrind in NUT sources for a helper tool"
+	+@cd $(builddir)/docs/man && $(MAKE) $(AM_MAKEFLAGS) FAKE_PAGES_BUMP_SRC=false distcheck-light-DIST_ALL_PAGES
 	+prefix='$${prefix}'; $(MAKE) $(AM_MAKEFLAGS) DISTCHECK_FLAGS="$(DISTCHECK_VALGRIND_FLAGS)" distcheck
+	@echo "Completed $@: relaxed distcheck, without man pages ('pre-built' placeholders in dist archive), running tests under valgrind" >&2
 else !HAVE_VALGRIND
 memcheck distcheck-valgrind:
+	@echo "Starting $@" >&2
 	@echo "See also scripts/valgrind in NUT sources for a helper tool"
 	@echo "SKIPPED $@ : valgrind was not detected on this system by configure script" >&2
 endif !HAVE_VALGRIND

NEWS.adoc

@@ -90,7 +90,7 @@ https://github.com/networkupstools/nut/milestone/11
      them. [#1245]
 
  - SEMVER, know thyself!
-   * development iterations of NUT should now identify with not only the
+   * Development iterations of NUT should now identify with not only the
      semantic version of a preceding release, but with git-derived information
      about the amount of iterations that followed (if available):
      the three-number "semver" would be seen on release snapshots, while
@@ -104,6 +104,7 @@ https://github.com/networkupstools/nut/milestone/11
      upgrades via development snapshots, eventually. A copy of the current
      version information would be embedded into "dist" archives as a
      `VERSION_DEFAULT` file, among provisions for packager tuning. [#1949]
+   * Documentation about this would be maintained in `docs/nut-versioning.adoc`
    * SMF manifests and systemd units now refer to man pages and their online
      variants under `NUT_WEBSITE_BASE` dependent on codebase maturity
      (development or release snapshot); many programs now display such
@@ -137,6 +138,25 @@ Overall, NUT CI farm build times got 25%+ shorter (which is important as
    and we suppose this is an interesting case for other projects to draw
    inspiration from for their recipe refactoring. [PR #2825]
 
+ - The `make dist` goal now takes more care to require availability of the man
+   pages to put into the prepared distribution archive. These may come either
+   from the current build, or inherited from its sources (if using a tarball
+   initially) on a platform without tooling required for man page generation.
++
+This requirement compromises usability of `make distcheck` on platforms without
+   such tools from sources without pre-built man pages (e.g. builds from git),
+   so a couple of new goals were introduced in PR #2842:
+   - `make distcheck-fake-man` generates placeholder files named like pre-built
+      man pages for any missing files, just for the purpose of constructing
+      a sane-looking dist archive to `distcheck` strictly otherwise;
+   - `make distcheck-ci` is routed to `distcheck` or `distcheck-fake-man`
+     based on build circumstances (ability to build man pages or presence
+     of pre-built pages, or lack of either);
+   - Similarly, `make dist-ci` is routed to provide a strict or faked tarball;
+   - Earlier defined goals like `distcheck-light` or `distcheck-valgrind` now
+     take advantage of these mechanisms to also produce usable dist archives
+     for their relaxed or purpose-specific tests.
+
  - the `upsnotify()` common code introduced in recent NUT releases (integrating
    with service management frameworks, etc.) was a bit cryptic when it reported
    a *failure to notify* (e.g. when not running as a service currently), fixed

README.adoc

@@ -242,6 +242,47 @@ revisions to make it more accessible to newcomers, as well as hardware vendor
 cooperation with first-hand driver and protocol submissions, and just about
 anything else you can think of.
 
+NUT Support Policy
+~~~~~~~~~~~~~~~~~~
+
+The Network UPS Tools project is a community-made open-source effort, primarily
+made and maintained by people donating their spare time.
+
+The support channels are likewise open, with preferred ones being
+link:https://github.com/networkupstools/nut/issues[the NUT project issue
+tracker on GitHub] and the NUT Users mailing list, as detailed at
+https://networkupstools.org/support.html page.
+
+Please keep in mind that any help is provided by community members just like
+yourself, as a best effort, and subject to their availability and experience.
+It is expected that you have read the Frequently Asked Questions, looked at
+the link:https://github.com/networkupstools/nut/wiki[NUT wiki], and have a
+good grasp about the three-layer design and programs involved in a running
+deployment of NUT, for a discussion to be constructive and efficient.
+
+Be patient, polite, and prepare to learn and provide information about your
+NUT deployment (version, configuration, OS...) and the device, to collect
+logs, and to answer any follow-up questions about your situation.
+
+Finally, note that NUT is packaged and delivered by packaging into numerous
+operating systems, appliances and monitoring projects, and may be bundled
+with third-party GUI clients.  It may be wise of end-users to identify such
+cases and ask for help on the most-relevant forum (or several, including the
+NUT support channels).  It is important to highlight that the NUT project
+releases have for a long time been essentially snapshots of better-tested
+code, and we do not normally issue patches to "hot-fix" any older releases.
+
+Any improvements of NUT itself are made in the current code base, same as
+any other feature development, so to receive desired fixes on your system
+(and/or to check that they do solve your particular issue), expect to be
+asked to build the recent development iteration from GitHub or work with
+your appliance vendor to get a software upgrade.
+
+Over time, downstream OS packaging or other integrations which use NUT, may
+issue patches as new package revisions, or new baseline versions of NUT,
+according to *their* release policies. It is not uncommon for distributions,
+especially "stable" flavours, to be a few years behind upstream projects.
+
 
 Installing
 ----------
@@ -724,15 +765,18 @@ configuration file.  It is not active by default.
 Version Numbering
 -----------------
 
-The version numbers work like this: if the middle number is odd, it's a
-development tree, otherwise it is the stable tree.
+The version numbers historically worked like this: if the middle number
+is odd, it's a development tree, otherwise it is the stable tree.
 
 The past stable trees were 1.0, 1.2, 1.4, 2.0, 2.2 and 2.4, with the
 latest such stable tree designated 2.6.  The development trees were 1.1,
 1.3, 1.5, 2.1 and 2.3.  Since the 2.4 release, there is no real separate
 development branch anymore since the code is available through a revision
-control system (namely, Git -- or actually Subversion back then) and its
-snapshots become published releases.
+control system (namely, Git -- or actually Subversion back then), development
+happens in feature branches that are eventually merged into the main trunk,
+and its snapshots become published releases. As a result, subsequent versions
+(2.7 and 2.8) were released without regard for even/odd values of the minor
+version component.
 
 Since 2.7 line of releases, sources are tracked in Git revision control
 system, with the project ecosystem being hosted on GitHub, and any code
@@ -751,6 +795,17 @@ This allows for a reasonably growing version of stable baseline and
 local development, so that experimental packages can be installed as
 upgrades (or well-exposed downgrades).
 
+While the NUT releases retain the semantic versioning three-component
+standard, interim builds (trunk snapshots and development branches)
+can expose a much more complex structure with the amount of commits
+in the trunk since last release, and amount of commits on the branch
+unique to it (not in the trunk). Additional data may include overall
+amount of commits in the current build since last release, and the
+git commit has identifier of the built code base.
+
+More details can be seen in `docs/nut-versioning.adoc` file in the
+NUT source code base.
+
 Backwards and Forwards Compatibility
 ------------------------------------
 

UPGRADING.adoc

@@ -42,6 +42,7 @@ Changes from 2.8.2 to 2.8.3
   if this is required, a (NUT_)VERSION_FORCED_SEMVER envvar or file can
   help identify the actual NUT release version triplet used on the box.
   Please use it, it immensely helps with community troubleshooting!
+  Documentation about this would be maintained in `docs/nut-versioning.adoc`
   [issue #1949]
 
 - When packaging or custom-building for (Linux) distributions with systemd,
@@ -57,6 +58,12 @@ Changes from 2.8.2 to 2.8.3
   depending on `target_cpu` of the build. If you had any scripts relying
   on the older pattern, they may have to be updated.
 
+- The `make dist` goal now takes more care to require availability of the
+  man pages to put into the prepared distribution archive. Development and CI
+  builds on platforms unable to fulfill this goal can use `make distcheck-ci`
+  (and `make dist-ci`) to fake presence of pre-built man pages with placeholder
+  files, to complete other aspects of `distcheck` validation. [#2842]
+
 - the PyPI distribution of the `PyNUTClient` module tarball should now use a
   lower-cased file name (and immediate versioned directory name inside) to
   match the requirements of link:https://peps.python.org/pep-0625/[PEP-0625].