ci: simplify docker workflow using actions-mn actions

.github/workflows/docker.yml

@@ -21,63 +21,23 @@ 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
+      - name: Restore cached Metanorma XML
         id: cache-mn-xml
         uses: actions/cache@v4
-        env:
-          cache-name: _site
         with:
           path: _site
+          key: ${{ runner.os }}-mn-site-${{ hashFiles('sources/**') }}
 
-          # 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
+      - uses: actions-mn/site-gen@v1
         if: steps.cache-mn-xml.outputs.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

.github/workflows/release.yml

@@ -5,6 +5,16 @@ on:
     branches: [main]
     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
@@ -14,5 +24,6 @@ jobs:
     uses: actions-mn/.github/.github/workflows/metanorma-release.yml@main
     with:
       default-visibility: private
+      include-pattern: ${{ github.event.inputs.include-pattern || '*' }}
+      force: ${{ github.event.inputs.force || 'false' }}
     secrets: inherit
-

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.