CI: finishing touches for make dist workflow and docs

.github/workflows/01-make-dist.yml

@@ -4,6 +4,7 @@
 # See also:
 #   https://github.com/actions/upload-artifact
 #   https://docs.github.com/en/actions/reference/workflows-and-actions/variables
+#   https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
 name: "GHA-01: Make dist and docs tarballs, see workflow page for links"
 
 on:
@@ -13,6 +14,11 @@ on:
       - v*
   pull_request_target:
     # The branches below must be a subset of the branches above
+    # Note that for PRs this runs the copy of workflow in the
+    # target branch (and only then gets some of the permissions
+    # listed below), and identification/naming of PR source vs.
+    # a pushed branch (e.g. master updated by a PR merge) is
+    # tricky.
     branches: [ "master", "FTY", "fightwarn", "FTY-obs" ]
   schedule:
     - cron: '15 12 * * 0'
@@ -32,42 +38,21 @@ jobs:
      #  Maybe https://aschmelyun.com/blog/using-docker-run-inside-of-github-actions/
      #  => https://github.com/addnab/docker-run-action can help
     runs-on: ubuntu-latest
-    #permissions:
-    #  #actions: read
-    #  actions: write
-    #  #contents: read
-    #  contents: write
-    #  repository-projects: write
-    #  security-events: write
-    #  pull-requests: write
-    #  issues: write
 
     strategy:
       fail-fast: false
 
     steps:
     # Post early so this would be about the top comment in the PR trail
     # (easy to see, contents replaced later)
-
-    #- name: "GHA-01: Make dist and docs tarballs - report download URL - t1"
-    #  uses: thollander/actions-comment-pull-request@v3
-    #  # if: startsWith(github.ref, 'refs/pull/')
-    #  continue-on-error: true
-    #  with:
-    #    comment-tag: latest-tarball
-    #    message: Sticky note -- Dist and Docs tarballs will be linked here after the "make dist" job completes.
-    #    #github-token: ${{ secrets.MAKE_DIST_TOKEN }}
-
-    - name: "GHA-01: Make dist and docs tarballs - report download URL - s1"
+    - name: "GHA-01: Make dist and docs tarballs - report download URL (placeholder) as a first-ever PR comment"
       uses: marocchino/sticky-pull-request-comment@v2
       if: startsWith(github.ref, 'refs/pull/') || github.event.pull_request.number > 0
       continue-on-error: true
       with:
         header: latest-tarball-sticky
         only_create: true
         message: Sticky note -- Dist and Docs tarballs will be linked here after the "make dist" job completes.
-        #github-token: ${{ secrets.MAKE_DIST_TOKEN }}
-        #GITHUB_TOKEN: ${{ secrets.MAKE_DIST_TOKEN }}
 
     - name: Checkout repository
       uses: actions/checkout@v5
@@ -76,8 +61,6 @@ jobs:
         fetch-tags: true
 
     # https://github.com/marketplace/actions/substitute-string
-    # https://docs.github.com/en/actions/reference/workflows-and-actions/variables
-    # https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
     # See also examples in https://github.com/dhimmel/dump-actions-context/
     # Note it warns about "unexpected input(s)" with replacement tokens below,
     # as they are by design not predefined, as far as actions API is concened.
@@ -88,7 +71,9 @@ jobs:
         _input-text: "${{ github.event.pull_request.number > 0 && format('PR-{0}', github.event.pull_request.number) || github.head_ref || github.ref_name }}"
         " ": _
         "/": _
-    - run: |
+
+    - name: Debug PR/branch identification
+      run: |
         echo "steps.subst-github-ref-name.outputs.result='${{ steps.subst-github-ref-name.outputs.result }}'" || true
         echo "github.event.pull_request.number='${{ github.event.pull_request.number }}'" || true
         echo "format('PR-{0}', github.event.pull_request.number)='${{ format('PR-{0}', github.event.pull_request.number) }}'" || true
@@ -270,7 +255,6 @@ jobs:
                 artifact_id: id,
               })
             })
-        #github-token: ${{ secrets.MAKE_DIST_TOKEN }}
 
     - name: Upload tarball and its checksum artifacts
       uses: actions/upload-artifact@v4
@@ -282,33 +266,20 @@ jobs:
         compression-level: 0
         overwrite: true
 
-    # https://github.com/thollander/actions-comment-pull-request
     # FIXME: Something that adds/updates Github Checks would be better
     #  as it would be seen in the list attached to a status icon of any
     #  build (e.g. history of master branch)
-
-    #- name: "GHA-01: Make dist and docs tarballs - report download URL - t2"
-    #  uses: thollander/actions-comment-pull-request@v3
-    #  # if: startsWith(github.ref, 'refs/pull/')
-    #  continue-on-error: true
-    #  with:
-    #    comment-tag: latest-tarball
-    #    message: Dist and Docs [NUT-tarballs-${{ steps.subst-github-ref-name.outputs.result }}.zip](${{ steps.upload_artifact.outputs.artifact-url }}) are available for commit ${{ github.event.pull_request.head.sha || github.sha }}
-    #    #github-token: ${{ secrets.MAKE_DIST_TOKEN }}
-
     # https://github.com/marocchino/sticky-pull-request-comment
-    - name: "GHA-01: Make dist and docs tarballs - report download URL - s2"
+    - name: "GHA-01: Make dist and docs tarballs - report download URL as a PR comment"
       uses: marocchino/sticky-pull-request-comment@v2
       if: startsWith(github.ref, 'refs/pull/') || github.event.pull_request.number > 0
       continue-on-error: true
       with:
         header: latest-tarball-sticky
         message: Dist and Docs [NUT-tarballs-${{ steps.subst-github-ref-name.outputs.result }}.zip](${{ steps.upload_artifact.outputs.artifact-url }}) are available for commit ${{ github.event.pull_request.head.sha || github.sha }}
-        #github-token: ${{ secrets.MAKE_DIST_TOKEN }}
-        #GITHUB_TOKEN: ${{ secrets.MAKE_DIST_TOKEN }}
 
     # https://github.com/marketplace/actions/commit-comment
-    - name: "GHA-01: Make dist and docs tarballs - report download URL - commit comment"
+    - name: "GHA-01: Make dist and docs tarballs - report download URL as a commit comment"
       uses: peter-evans/commit-comment@v4
       continue-on-error: true
       with:

NEWS.adoc

@@ -273,8 +273,11 @@ several `FSD` notifications into one executed action. [PR #3097]
 
  - Added a GitHub Actions CI job to generate, upload and recycle `make dist`
    and `make dist-docs` tarballs so they are easier to obtain for people and
-   other CI systems (which might not want to follow a Git repository). [#1400,
-   #2829]
+   other CI systems (which might not want to follow a Git repository). Links
+   to these artifacts can be seen in workflow page (or its logs), sticky note
+   on top of PR comments, and added as commit comments (seen after the diff of
+   the commit, see e.g. merge commits for the `master` branch). Note that the
+   GitHub Action storage keeps artefacts for at most 90 days. [#1400, #2829]
 
  - Source directory `data/html` was renamed to `data/htmlcgi` in order to
    better reflect its contents and purpose, compared to documentation-oriented

docs/download.txt

@@ -8,6 +8,28 @@ This section presents the different methods to download NUT.
 // https://networkupstools.org/download.html
 //////////////////////////////////////////////////////////////////////////////
 
+Building from source code
+-------------------------
+
+To build from Git sources, you will need a number of tools such as `autoconf`,
+`automake` and `libtool` to use these checkouts or snapshots to generate the
+`configure` script and some other files.  The distribution archives already
+include the `configure` script (as well as other files) and do not require
+auto* tools to prepare the sources for a build.
+
+A more complete list of build prerequisites for different platforms can be seen in
+link:https://networkupstools.org/docs/qa-guide.chunked/_prerequisites_for_building_nut_on_different_oses.html[Prerequisites
+for building NUT on different OSes] chapter in the
+link:https://networkupstools.org/docs/qa-guide.chunked/[NUT QA Guide],
+and reading about
+link:https://networkupstools.org/docs/user-manual.chunked/Configure_options.html[`configure`
+script options] can also help.
+
+After you `configure` the source workspace, a `make dist-hash` recipe would
+create the snapshot tarballs which do not require the `auto*` tools, and their
+checksum files, such as those available on the NUT website and attached to
+link:https://github.com/networkupstools/nut/releases[GitHub Releases page].
+
 Source code
 -----------
 
@@ -44,6 +66,23 @@ You can also browse the link:https://www.networkupstools.org/source/{tree_versio
 Development tree:
 ~~~~~~~~~~~~~~~~~
 
+To get the newest fixes or features, you may want to build code that is
+even newer than the most-recent NUT release (and likely much newer than
+whatever your OS distribution has packaged).  This bleeding-edge approach
+usually involves building NUT either from the `master` branch, or even
+from feature branches which are sources of a pull request being reviewed
+and discussed before it gets merged into the main development trunk.
+
+As such, it is highly recommended to build from Git sources rather than
+"distribution tarball" archives (so you can more easily update your build
+workspace to try subsequent iterations), although the latter are now also
+available for development iterations.
+
+See the live Wiki article on
+https://github.com/networkupstools/nut/wiki/Building-NUT-for-in%E2%80%90place-upgrades-or-non%E2%80%90disruptive-tests
+for latest suggestions for building, testing and installing the latest
+NUT code base.
+
 Code repository
 ^^^^^^^^^^^^^^^
 
@@ -99,29 +138,20 @@ sources of operating system distributions, as listed below.
 Snapshots
 ^^^^^^^^^
 
-GitHub has several download links for repository snapshots (for particular tags
-or branches), but you will need a number of tools such as `autoconf`, `automake`
-and `libtool` to use these snapshots to generate the `configure` script and some
-other files.
-
-After you `configure` the source workspace, a `make dist-hash` recipe would
-create the snapshot tarballs which do not require the `auto*` tools, and their
-checksum files, such as those available on the NUT website and attached to
-link:https://github.com/networkupstools/nut/releases[GitHub Releases page].
-
-Note that the ability to build NUT seamlessly from ZIP or `tar.gz` snapshots
-prepared by GitHub automatically (as `git archive` of a checked-out workspace)
-is not regularly checked or "supported" by the Network UPS Tools project. YMMV.
+For pull requests and eventual merges into the master branch, a NUT CI job
+prepares correct "dist tarballs" with a snapshot of source code, as well as
+an archive with rendered documentation files (PDF, HTML, man pages).
 
-/////////
-TODO: #1400 to replace this with a NUT CI farm service to publish the tarballs
+Links to these "Dist and Docs" archives can be seen on GitHub in merge commit
+comments, and are posted as a rolling comment in pull requests. Keep in mind
+that artefacts like these are stored for up to 90 days, and can be rotated
+away earlier.
 
-If our Buildbot instance is behaving, you can download a snapshot which does
-not require auto* tools from this
-link:http://buildbot.networkupstools.org/snapshots[builder].  Look for the
-latest *[tarball]* link towards the top of the page, and be sure to check the
-'Build ##' link to verify the branch name.
-/////////
+NOTE: GitHub has several download links for repository snapshots (made for
+particular tags or branches), but the ability to build NUT seamlessly from
+ZIP or `tar.gz` snapshots prepared by GitHub automatically (as a simple
+`git archive` of a checked-out workspace) is not regularly checked nor
+"supported" by the Network UPS Tools project. YMMV.
 
 Older versions
 ~~~~~~~~~~~~~~