From d36f96f488a746e19ccd47e7e6631cca5ea7fefc Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Sat, 8 Nov 2025 23:22:51 +0100 Subject: [PATCH 1/8] .github/workflows/01-make-dist.yml: update comments [#1400] Signed-off-by: Jim Klimov --- .github/workflows/01-make-dist.yml | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/.github/workflows/01-make-dist.yml b/.github/workflows/01-make-dist.yml index d2f9d450f8..f9db907d6d 100644 --- a/.github/workflows/01-make-dist.yml +++ b/.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' @@ -76,8 +82,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 +92,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 From 7eef1e3751d43633a003512b3c8c194ed9c46267 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Sat, 8 Nov 2025 23:26:15 +0100 Subject: [PATCH 2/8] .github/workflows/01-make-dist.yml: drop superfluous comment-posting action [#1400] Signed-off-by: Jim Klimov --- .github/workflows/01-make-dist.yml | 29 +++-------------------------- 1 file changed, 3 insertions(+), 26 deletions(-) diff --git a/.github/workflows/01-make-dist.yml b/.github/workflows/01-make-dist.yml index f9db907d6d..dd2d3fa9a9 100644 --- a/.github/workflows/01-make-dist.yml +++ b/.github/workflows/01-make-dist.yml @@ -54,17 +54,7 @@ jobs: 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 @@ -72,8 +62,6 @@ jobs: 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 @@ -288,22 +276,11 @@ 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 @@ -314,7 +291,7 @@ jobs: #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: From 8b7fdb3bdd8dd7915846e7c7e4ebd230293dd6c6 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Sat, 8 Nov 2025 23:32:34 +0100 Subject: [PATCH 3/8] NEWS.adoc: update about links to automatic dist tarballs [#1400] Signed-off-by: Jim Klimov --- NEWS.adoc | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/NEWS.adoc b/NEWS.adoc index 202991a6ec..3ec41d35ae 100644 --- a/NEWS.adoc +++ b/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 From 882f4bb42b67eb91b464c118ce9fd8708085de33 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Sat, 8 Nov 2025 23:42:10 +0100 Subject: [PATCH 4/8] docs/download.txt: add intro for development sources chapter [#1400] Signed-off-by: Jim Klimov --- docs/download.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/download.txt b/docs/download.txt index 251ade1c9a..a721eca4c5 100644 --- a/docs/download.txt +++ b/docs/download.txt @@ -44,6 +44,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 ^^^^^^^^^^^^^^^ From 1c97535720cda6591e21d4e602b8fa9c5ac66cac Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Sat, 8 Nov 2025 23:53:52 +0100 Subject: [PATCH 5/8] docs/download.txt: move notes about building from source upwards [#1400] Signed-off-by: Jim Klimov --- docs/download.txt | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/download.txt b/docs/download.txt index a721eca4c5..88920f8917 100644 --- a/docs/download.txt +++ b/docs/download.txt @@ -8,6 +8,24 @@ This section presents the different methods to download NUT. // https://networkupstools.org/download.html ////////////////////////////////////////////////////////////////////////////// +Building from source code +------------------------- + +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. A more complete list 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 ----------- @@ -116,19 +134,11 @@ 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. +GitHub has several download links for repository snapshots (for particular +tags or branches), but note that the ability to build NUT seamlessly from +ZIP or `tar.gz` snapshots prepared by GitHub automatically (as a `git archive` +of a checked-out workspace) is not regularly checked nor "supported" by the +Network UPS Tools project. YMMV. ///////// TODO: #1400 to replace this with a NUT CI farm service to publish the tarballs From db512036d1bf35b9e51156760282d54d9c0f4426 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Sun, 9 Nov 2025 00:09:05 +0100 Subject: [PATCH 6/8] docs/download.txt: revise notes on snapshots (not only GitHub now) and build types (git/dist) [#1400] Signed-off-by: Jim Klimov --- docs/download.txt | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/docs/download.txt b/docs/download.txt index 88920f8917..0d440260bf 100644 --- a/docs/download.txt +++ b/docs/download.txt @@ -11,9 +11,13 @@ This section presents the different methods to download NUT. Building from source code ------------------------- -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. A more complete list for different platforms can be seen in +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], @@ -134,21 +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 note that the ability to build NUT seamlessly from -ZIP or `tar.gz` snapshots prepared by GitHub automatically (as a `git archive` -of a checked-out workspace) is not regularly checked nor "supported" by the -Network UPS Tools project. YMMV. - -///////// -TODO: #1400 to replace this with a NUT CI farm service to publish the tarballs - -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. -///////// +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). + +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. + +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 ~~~~~~~~~~~~~~ From 4f5825f83d1ff371016668e939725a0a5fcf2821 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Sun, 9 Nov 2025 00:10:52 +0100 Subject: [PATCH 7/8] .github/workflows/01-make-dist.yml: drop commented-away permissions [#1400] Signed-off-by: Jim Klimov --- .github/workflows/01-make-dist.yml | 9 --------- 1 file changed, 9 deletions(-) diff --git a/.github/workflows/01-make-dist.yml b/.github/workflows/01-make-dist.yml index dd2d3fa9a9..86480a9605 100644 --- a/.github/workflows/01-make-dist.yml +++ b/.github/workflows/01-make-dist.yml @@ -38,15 +38,6 @@ 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 From c73811c8dc19f58bcae0edfd8fa1d2d4e6554c4c Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Sun, 9 Nov 2025 00:11:34 +0100 Subject: [PATCH 8/8] .github/workflows/01-make-dist.yml: drop MAKE_DIST_TOKEN [#1400] Signed-off-by: Jim Klimov --- .github/workflows/01-make-dist.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/01-make-dist.yml b/.github/workflows/01-make-dist.yml index 86480a9605..460742d605 100644 --- a/.github/workflows/01-make-dist.yml +++ b/.github/workflows/01-make-dist.yml @@ -255,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 @@ -278,8 +277,6 @@ jobs: 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 as a commit comment"