Skip to content

Commit 6864b38

Browse files
jimklimovjimklimov
authored
Merge branch 'master' into master
2 parents df2ddb0 + 23814de commit 6864b38

3 files changed

Lines changed: 81 additions & 68 deletions

File tree

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

Lines changed: 25 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
# See also:
55
# https://github.com/actions/upload-artifact
66
# https://docs.github.com/en/actions/reference/workflows-and-actions/variables
7+
# https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
78
name: "GHA-01: Make dist and docs tarballs, see workflow page for links"
89

910
on:
@@ -13,14 +14,19 @@ on:
1314
- v*
1415
pull_request_target:
1516
# The branches below must be a subset of the branches above
17+
# Note that for PRs this runs the copy of workflow in the
18+
# target branch (and only then gets some of the permissions
19+
# listed below), and identification/naming of PR source vs.
20+
# a pushed branch (e.g. master updated by a PR merge) is
21+
# tricky.
1622
branches: [ "master", "FTY", "fightwarn", "FTY-obs" ]
1723
schedule:
1824
- cron: '15 12 * * 0'
1925
workflow_dispatch:
2026
# Allow manually running the action, e.g. if disabled after some quietness in the source
2127

2228
permissions:
23-
contents: read
29+
contents: write
2430
issues: write
2531
pull-requests: write
2632

@@ -29,43 +35,24 @@ jobs:
2935
name: Make Dist and Docs Tarballs
3036
# FIXME: Prepare/maintain a container image with pre-installed
3137
# NUT build/tooling prereqs (save about 3 minutes per run!)
38+
# Maybe https://aschmelyun.com/blog/using-docker-run-inside-of-github-actions/
39+
# => https://github.com/addnab/docker-run-action can help
3240
runs-on: ubuntu-latest
33-
#permissions:
34-
# #actions: read
35-
# actions: write
36-
# #contents: read
37-
# contents: write
38-
# repository-projects: write
39-
# security-events: write
40-
# pull-requests: write
41-
# issues: write
4241

4342
strategy:
4443
fail-fast: false
4544

4645
steps:
4746
# Post early so this would be about the top comment in the PR trail
4847
# (easy to see, contents replaced later)
49-
50-
#- name: "GHA-01: Make dist and docs tarballs - report download URL - t1"
51-
# uses: thollander/actions-comment-pull-request@v3
52-
# # if: startsWith(github.ref, 'refs/pull/')
53-
# continue-on-error: true
54-
# with:
55-
# comment-tag: latest-tarball
56-
# message: Sticky note -- Dist and Docs tarballs will be linked here after the "make dist" job completes.
57-
# #github-token: ${{ secrets.MAKE_DIST_TOKEN }}
58-
59-
- name: "GHA-01: Make dist and docs tarballs - report download URL - s1"
48+
- name: "GHA-01: Make dist and docs tarballs - report download URL (placeholder) as a first-ever PR comment"
6049
uses: marocchino/sticky-pull-request-comment@v2
61-
if: startsWith(github.ref, 'refs/pull/')
50+
if: startsWith(github.ref, 'refs/pull/') || github.event.pull_request.number > 0
6251
continue-on-error: true
6352
with:
6453
header: latest-tarball-sticky
6554
only_create: true
6655
message: Sticky note -- Dist and Docs tarballs will be linked here after the "make dist" job completes.
67-
#github-token: ${{ secrets.MAKE_DIST_TOKEN }}
68-
#GITHUB_TOKEN: ${{ secrets.MAKE_DIST_TOKEN }}
6956

7057
- name: Checkout repository
7158
uses: actions/checkout@v5
@@ -74,18 +61,25 @@ jobs:
7461
fetch-tags: true
7562

7663
# https://github.com/marketplace/actions/substitute-string
77-
# https://docs.github.com/en/actions/reference/workflows-and-actions/variables
78-
# https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
64+
# See also examples in https://github.com/dhimmel/dump-actions-context/
7965
# Note it warns about "unexpected input(s)" with replacement tokens below,
8066
# as they are by design not predefined, as far as actions API is concened.
8167
# They still work for substitutions though.
8268
- uses: bluwy/substitute-string-action@v3
8369
id: subst-github-ref-name
8470
with:
85-
_input-text: "${{ github.head_ref || github.ref_name }}"
71+
_input-text: "${{ github.event.pull_request.number > 0 && format('PR-{0}', github.event.pull_request.number) || github.head_ref || github.ref_name }}"
8672
" ": _
8773
"/": _
88-
- run: echo "${{ steps.subst-github-ref-name.outputs.result }}"
74+
75+
- name: Debug PR/branch identification
76+
run: |
77+
echo "steps.subst-github-ref-name.outputs.result='${{ steps.subst-github-ref-name.outputs.result }}'" || true
78+
echo "github.event.pull_request.number='${{ github.event.pull_request.number }}'" || true
79+
echo "format('PR-{0}', github.event.pull_request.number)='${{ format('PR-{0}', github.event.pull_request.number) }}'" || true
80+
echo "github.head_ref='${{ github.head_ref }}'" || true
81+
echo "github.ref='${{ github.ref }}'" || true
82+
echo "github.ref_name='${{ github.ref_name }}'" || true
8983
9084
# Make build identification more useful (so we use no fallbacks in script)
9185
- name: Try to get more Git metadata
@@ -261,7 +255,6 @@ jobs:
261255
artifact_id: id,
262256
})
263257
})
264-
#github-token: ${{ secrets.MAKE_DIST_TOKEN }}
265258
266259
- name: Upload tarball and its checksum artifacts
267260
uses: actions/upload-artifact@v4
@@ -273,33 +266,20 @@ jobs:
273266
compression-level: 0
274267
overwrite: true
275268

276-
# https://github.com/thollander/actions-comment-pull-request
277269
# FIXME: Something that adds/updates Github Checks would be better
278270
# as it would be seen in the list attached to a status icon of any
279271
# build (e.g. history of master branch)
280-
281-
#- name: "GHA-01: Make dist and docs tarballs - report download URL - t2"
282-
# uses: thollander/actions-comment-pull-request@v3
283-
# # if: startsWith(github.ref, 'refs/pull/')
284-
# continue-on-error: true
285-
# with:
286-
# comment-tag: latest-tarball
287-
# 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 }}
288-
# #github-token: ${{ secrets.MAKE_DIST_TOKEN }}
289-
290272
# https://github.com/marocchino/sticky-pull-request-comment
291-
- name: "GHA-01: Make dist and docs tarballs - report download URL - s2"
273+
- name: "GHA-01: Make dist and docs tarballs - report download URL as a PR comment"
292274
uses: marocchino/sticky-pull-request-comment@v2
293-
if: startsWith(github.ref, 'refs/pull/')
275+
if: startsWith(github.ref, 'refs/pull/') || github.event.pull_request.number > 0
294276
continue-on-error: true
295277
with:
296278
header: latest-tarball-sticky
297279
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 }}
298-
#github-token: ${{ secrets.MAKE_DIST_TOKEN }}
299-
#GITHUB_TOKEN: ${{ secrets.MAKE_DIST_TOKEN }}
300280

301281
# https://github.com/marketplace/actions/commit-comment
302-
- name: "GHA-01: Make dist and docs tarballs - report download URL - commit comment"
282+
- name: "GHA-01: Make dist and docs tarballs - report download URL as a commit comment"
303283
uses: peter-evans/commit-comment@v4
304284
continue-on-error: true
305285
with:

‎NEWS.adoc‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -275,8 +275,11 @@ several `FSD` notifications into one executed action. [PR #3097]
275275

276276
- Added a GitHub Actions CI job to generate, upload and recycle `make dist`
277277
and `make dist-docs` tarballs so they are easier to obtain for people and
278-
other CI systems (which might not want to follow a Git repository). [#1400,
279-
#2829]
278+
other CI systems (which might not want to follow a Git repository). Links
279+
to these artifacts can be seen in workflow page (or its logs), sticky note
280+
on top of PR comments, and added as commit comments (seen after the diff of
281+
the commit, see e.g. merge commits for the `master` branch). Note that the
282+
GitHub Action storage keeps artefacts for at most 90 days. [#1400, #2829]
280283

281284
- Source directory `data/html` was renamed to `data/htmlcgi` in order to
282285
better reflect its contents and purpose, compared to documentation-oriented

‎docs/download.txt‎

Lines changed: 51 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,28 @@ This section presents the different methods to download NUT.
88
// https://networkupstools.org/download.html
99
//////////////////////////////////////////////////////////////////////////////
1010

11+
Building from source code
12+
-------------------------
13+
14+
To build from Git sources, you will need a number of tools such as `autoconf`,
15+
`automake` and `libtool` to use these checkouts or snapshots to generate the
16+
`configure` script and some other files. The distribution archives already
17+
include the `configure` script (as well as other files) and do not require
18+
auto* tools to prepare the sources for a build.
19+
20+
A more complete list of build prerequisites for different platforms can be seen in
21+
link:https://networkupstools.org/docs/qa-guide.chunked/_prerequisites_for_building_nut_on_different_oses.html[Prerequisites
22+
for building NUT on different OSes] chapter in the
23+
link:https://networkupstools.org/docs/qa-guide.chunked/[NUT QA Guide],
24+
and reading about
25+
link:https://networkupstools.org/docs/user-manual.chunked/Configure_options.html[`configure`
26+
script options] can also help.
27+
28+
After you `configure` the source workspace, a `make dist-hash` recipe would
29+
create the snapshot tarballs which do not require the `auto*` tools, and their
30+
checksum files, such as those available on the NUT website and attached to
31+
link:https://github.com/networkupstools/nut/releases[GitHub Releases page].
32+
1133
Source code
1234
-----------
1335

@@ -44,6 +66,23 @@ You can also browse the link:https://www.networkupstools.org/source/{tree_versio
4466
Development tree:
4567
~~~~~~~~~~~~~~~~~
4668

69+
To get the newest fixes or features, you may want to build code that is
70+
even newer than the most-recent NUT release (and likely much newer than
71+
whatever your OS distribution has packaged). This bleeding-edge approach
72+
usually involves building NUT either from the `master` branch, or even
73+
from feature branches which are sources of a pull request being reviewed
74+
and discussed before it gets merged into the main development trunk.
75+
76+
As such, it is highly recommended to build from Git sources rather than
77+
"distribution tarball" archives (so you can more easily update your build
78+
workspace to try subsequent iterations), although the latter are now also
79+
available for development iterations.
80+
81+
See the live Wiki article on
82+
https://github.com/networkupstools/nut/wiki/Building-NUT-for-in%E2%80%90place-upgrades-or-non%E2%80%90disruptive-tests
83+
for latest suggestions for building, testing and installing the latest
84+
NUT code base.
85+
4786
Code repository
4887
^^^^^^^^^^^^^^^
4988

@@ -99,29 +138,20 @@ sources of operating system distributions, as listed below.
99138
Snapshots
100139
^^^^^^^^^
101140

102-
GitHub has several download links for repository snapshots (for particular tags
103-
or branches), but you will need a number of tools such as `autoconf`, `automake`
104-
and `libtool` to use these snapshots to generate the `configure` script and some
105-
other files.
106-
107-
After you `configure` the source workspace, a `make dist-hash` recipe would
108-
create the snapshot tarballs which do not require the `auto*` tools, and their
109-
checksum files, such as those available on the NUT website and attached to
110-
link:https://github.com/networkupstools/nut/releases[GitHub Releases page].
111-
112-
Note that the ability to build NUT seamlessly from ZIP or `tar.gz` snapshots
113-
prepared by GitHub automatically (as `git archive` of a checked-out workspace)
114-
is not regularly checked or "supported" by the Network UPS Tools project. YMMV.
141+
For pull requests and eventual merges into the master branch, a NUT CI job
142+
prepares correct "dist tarballs" with a snapshot of source code, as well as
143+
an archive with rendered documentation files (PDF, HTML, man pages).
115144

116-
/////////
117-
TODO: #1400 to replace this with a NUT CI farm service to publish the tarballs
145+
Links to these "Dist and Docs" archives can be seen on GitHub in merge commit
146+
comments, and are posted as a rolling comment in pull requests. Keep in mind
147+
that artefacts like these are stored for up to 90 days, and can be rotated
148+
away earlier.
118149

119-
If our Buildbot instance is behaving, you can download a snapshot which does
120-
not require auto* tools from this
121-
link:http://buildbot.networkupstools.org/snapshots[builder]. Look for the
122-
latest *[tarball]* link towards the top of the page, and be sure to check the
123-
'Build ##' link to verify the branch name.
124-
/////////
150+
NOTE: GitHub has several download links for repository snapshots (made for
151+
particular tags or branches), but the ability to build NUT seamlessly from
152+
ZIP or `tar.gz` snapshots prepared by GitHub automatically (as a simple
153+
`git archive` of a checked-out workspace) is not regularly checked nor
154+
"supported" by the Network UPS Tools project. YMMV.
125155

126156
Older versions
127157
~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)