diff --git a/.github/workflows/01-make-dist.yml b/.github/workflows/01-make-dist.yml index d2f9d450f8..460742d605 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' @@ -32,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 @@ -48,17 +45,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 @@ -66,8 +53,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 @@ -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: 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 diff --git a/docs/download.txt b/docs/download.txt index 251ade1c9a..0d440260bf 100644 --- a/docs/download.txt +++ b/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 ~~~~~~~~~~~~~~