From 903fa385942ddd23030cf8a10a93b441673fbc16 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Mon, 11 May 2026 11:04:15 +0800 Subject: [PATCH 1/3] ci: simplify docker workflow using actions-mn actions Replace metanorma/ci/docker-gem-install@main (which fails with bundler exit code 5) and manual actions/cache@v4 logic with actions-mn/cache@v1 and actions-mn/site-gen@v1. The actions-mn actions handle font caching, manifest-based site caching, and metanorma site generation internally, eliminating the need for a separate bundler install step. --- .github/workflows/docker.yml | 57 +++++------------------------------- 1 file changed, 8 insertions(+), 49 deletions(-) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index ce691a3..9e7856f 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -21,63 +21,22 @@ jobs: container: image: metanorma/metanorma:latest steps: - - name: Checkout - uses: actions/checkout@v4 + - uses: actions/checkout@v4 with: submodules: true - - name: Bundler install - uses: metanorma/ci/docker-gem-install@main - - - name: Print Metanorma version - run: metanorma --version - # In case of cache miss, the generate MN XML step will run - # and the cache will be filled after job finishes. - # Next time it’ll be a cache hit, unless sources changed. - # See also “Upload cached Metanorma XML” step, which is important. - - name: Restore cached Metanorma XML, if any - id: cache-mn-xml - uses: actions/cache@v4 - env: - cache-name: _site + - uses: actions-mn/cache@v1 + id: mn-cache with: - path: _site + cache-site-for-manifest: metanorma.yml + cache-site-path: _site - # NOTE: cache key does not include current MN version, - # which means if sources did not change but it’s desirable - # to rebuild XML using a newer MN version it may be impossible to do - # without making a dummy/meaningless change in the content - # to change the hash. - # - # The proper way to address this could be pinning MN version - # somewhere and including it as part of the hash here; - # alternatively, if we really want to always use whatever MN version - # is latest, we could detect that version and include it - # as part of this key. - key: ${{ runner.os }}-mn-${{ env.cache-name }}-${{ hashFiles('sources/**', 'Gemfile.lock') }} - - # We can fuzzy-match latest available cache, - # instead of precise hash. - # This can speed up build in some scenarios, - # but can in theory also cause issues where XML is not updated - # after source changes. - # restore-keys: | - # ${{ runner.os }}-mn-${{ env.cache-name }}- - # ${{ runner.os }}-mn- - # ${{ runner.os }}- - - - name: Generate Metanorma XML - uses: actions-mn/build-and-publish@v2 - if: steps.cache-mn-xml.outputs.cache-hit != 'true' + - uses: actions-mn/site-gen@v1 + if: steps.mn-cache.outputs.cache-site-cache-hit != 'true' with: - destination: artifact - artifact-name: mn agree-to-terms: true - # In case of cache hit, we must explicitly upload the _site dir as artifact - - name: Upload cached Metanorma XML - uses: actions/upload-artifact@v4 - if: steps.cache-mn-xml.outputs.cache-hit == 'true' + - uses: actions/upload-artifact@v4 with: name: mn path: _site From d3f9123428c89b9b892f88a261ca852dcc209656 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Mon, 11 May 2026 11:10:37 +0800 Subject: [PATCH 2/3] ci: drop actions-mn/cache (incompatible with Docker container) The actions-mn/cache@v1 is a composite action that uses actions/github-script internally, which fails inside Docker containers with ERR_PACKAGE_PATH_NOT_EXPORTED. Keep actions/cache@v4 for site output caching, and use actions-mn/site-gen@v1 for the build step. --- .github/workflows/docker.yml | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 9e7856f..def70d7 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -25,14 +25,15 @@ jobs: with: submodules: true - - uses: actions-mn/cache@v1 - id: mn-cache + - name: Restore cached Metanorma XML + id: cache-mn-xml + uses: actions/cache@v4 with: - cache-site-for-manifest: metanorma.yml - cache-site-path: _site + path: _site + key: ${{ runner.os }}-mn-site-${{ hashFiles('sources/**') }} - uses: actions-mn/site-gen@v1 - if: steps.mn-cache.outputs.cache-site-cache-hit != 'true' + if: steps.cache-mn-xml.outputs.cache-hit != 'true' with: agree-to-terms: true From 62b9c8e1680b98e407cc3261486bf3bf91bb8af3 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Mon, 11 May 2026 18:28:13 +0800 Subject: [PATCH 3/3] docs: add release instructions to README Explain how the release workflow uses normalized document identifiers from RXL metadata (not source directory names) for pattern matching. Add workflow_dispatch inputs for include-pattern and force. --- .github/workflows/release.yml | 14 ++++++- README.adoc | 74 +++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 09b91ef..651185d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -3,8 +3,18 @@ name: Release on: push: branches: [main] - paths: ['sources/**', 'metanorma.yml'] + paths: ['sources/**', 'metanorma.yml', 'metanorma.release.yml'] workflow_dispatch: + inputs: + include-pattern: + description: 'Glob pattern to filter documents for release (e.g. cc-1903*)' + required: false + default: '*' + force: + description: 'Force release even if content is unchanged' + required: false + type: boolean + default: false permissions: contents: write @@ -25,3 +35,5 @@ jobs: - uses: actions-mn/release@v1 with: token: ${{ secrets.GITHUB_TOKEN }} + include-pattern: ${{ github.event.inputs.include-pattern || '*' }} + force: ${{ github.event.inputs.force || 'false' }} diff --git a/README.adoc b/README.adoc index c8d8edc..113411b 100644 --- a/README.adoc +++ b/README.adoc @@ -85,6 +85,80 @@ Index of all documents:: `_site/index.html` Individual document outputs:: `_site/documents/` (HTML, PDF, MN XML) +== Releasing documents + +Documents are released as per-document GitHub Releases using the Release +workflow. Each document is identified by its normalized docidentifier +(derived from the RXL metadata: lowercased, non-alphanumeric characters +replaced with hyphens). For example, `CC/A 0402:2004` becomes +`cc-a-0402-2004`. + +A release is triggered automatically when source files change on `main`, +or manually via workflow dispatch. + +=== Automatic release + +Push changes to `sources/**`, `metanorma.yml`, or `metanorma.release.yml` +on `main`. The workflow compiles all documents and releases only those +whose compiled output has changed (detected via content hashing). + +=== Manual release (all documents) + +Go to *Actions → Release → Run workflow* and click *Run workflow* with +the defaults. This re-evaluates all documents but only re-releases those +with changed content. + +=== Manual release (specific documents) + +Go to *Actions → Release → Run workflow* and set *include-pattern* to +match the document's normalized identifier. The pattern uses minimatch +glob syntax and is matched against the identifier extracted from each +document's RXL file. For example: + +[cols="1,3"] +|=== +| Pattern | Matches + +| `cc-a-1903*` +| All documents with docnumbers starting with 1903 + +| `cc-a-0904*` +| The document `CC/A 0904:2009` (xCal) + +| `*0402*` +| The document `CC/A 0402:2004` (IOP test results) + +| `*roundtable*` +| No match (pattern filters by identifier, not directory name) +|=== + +TIP: To find a document's identifier, check the `:docnumber:` attribute +in its `document.adoc`. The normalized identifier follows the pattern +`cc-a-{docnumber}-{copyright-year}`. + +=== Force re-release + +Check *force* in the workflow dispatch form to release matching documents +even if their content hash is unchanged (e.g. after a Metanorma version +update). Existing published releases are immutable and will not be +overwritten; only draft releases are updated in-place. + +=== Controlling visibility + +Create a `metanorma.release.yml` file to control which documents are +released publicly: + +[source,yaml] +---- +documents: + - source: sources/cc-1903-report-conference-46/document.adoc + - source: sources/cc-1902-report-conference-45/document.adoc + visibility: private +---- + +When this file is absent, all documents are released. + +// // == License Copyright CalConnect.