From e49bfdedb0d0248038d09889b1a8140e78b6277e Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Mon, 5 Feb 2024 19:19:31 -0800 Subject: [PATCH 1/4] document caching --- .github/workflows/docker-publish.yml | 7 +--- .github/workflows/render-samples.yml | 7 +--- guide.md | 62 ++++++++++++++++------------ 3 files changed, 38 insertions(+), 38 deletions(-) diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 4cd69b9..e842ccf 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -120,12 +120,7 @@ jobs: env: cache-name: cache-latex-files with: - path: | - *.aux - *.fdb_latexmk - *.lof - *.lot - *.toc + path: *.aux *.fdb_latexmk *.lof *.lot *.toc key: latex - name: Render for release diff --git a/.github/workflows/render-samples.yml b/.github/workflows/render-samples.yml index cb7afd8..72b9056 100644 --- a/.github/workflows/render-samples.yml +++ b/.github/workflows/render-samples.yml @@ -62,12 +62,7 @@ jobs: env: cache-name: cache-latex-files with: - path: | - *.aux - *.fdb_latexmk - *.lof - *.lot - *.toc + path: *.aux *.fdb_latexmk *.lof *.lot *.toc key: latex - name: Run the action on guide diff --git a/guide.md b/guide.md index e951a75..bba3e21 100644 --- a/guide.md +++ b/guide.md @@ -101,26 +101,23 @@ Even if you used the template repository, please double-check this. As the tools are being actively developed, there is probably a newer version of the tools available for you! -::: Caveat ::: +:::::::::::::::::::::::::::::::::::: Note ::::::::::::::::::::::::::::::::::::: Use `ghcr.io/trustedcomputinggroup/pandoc:latest` at your own risk. As the tools may change defaults from version to version, it is better to pin your doc to a particular version of the tools and periodically update the tools as needed. -:::::::::::::: +::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: -A typical Markdown-in-GitHub spec might want to automate the following: +A typical GitHub Markdown repo will: -* Render the spec to PDF on every pull request so that reviewers can check it. -* Render the spec to PDF and Word on every release and attach to the release - page. +* Render the spec to PDF and Word on pull requests and attach them to the PR. +* Render the spec to PDF and Word on releases and attach them to the release. +* Cache the LaTex intermediate files to the GitHub actions cache. This allows + small changes to the doc to render faster. `.github/workflows/actions.yml` might look a bit like this: ```yaml -# Render the spec to PDF and Word on pull requests and releases, attaching the -# outputs to the pull request / release, as appropriate. - name: Render spec - on: pull_request: release: @@ -135,6 +132,17 @@ jobs: steps: - name: Checkout uses: actions/checkout@v3 + with: + fetch-depth: 0 + fetch-tags: true + + - name: Cache LaTeX files + uses: actions/cache@v3 + env: + cache-name: cache-latex-files + with: + path: *.aux *.fdb_latexmk *.lof *.lot *.toc + key: latex - name: Render uses: trustedcomputinggroup/markdown@v0.4.2 @@ -347,11 +355,11 @@ If you have GitHub Actions for rendering the spec for releases (see 5. A few minutes later, the PDF and DOCX of the spec will appear on the page for that release (you can monitor this on the "Actions" page). -::: Tip ::: +:::::::::::::::::::::::::::::::::::: Note ::::::::::::::::::::::::::::::::::::: When balloting or sending a document to the TC for review, please create a docx diff from Microsoft Word, comparing the docx outputs attached between releases with Word's "Compare Versions" tool. -::::::::::: +::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: # Using Markdown @@ -475,7 +483,7 @@ TCG uses a special visual style to demarcate informative non-binding remarks wit To create an informative note, use the following syntax: ```md -::: Informative ::: +::::::::::::::::::::::::::::::::: Informative ::::::::::::::::::::::::::::::::: This is the only informative text block in this document. These blocks can contain multiple paragraphs. @@ -488,26 +496,28 @@ too large in an Informative Text block. | SPECIFICATION | Usually | | GUIDANCE | Rarely | | REFERENCE | Rarely | -::::::::::::::::::: +::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ``` The above Markdown code becomes: -::: Informative ::: +::::::::::::::::::::::::::::::::: Informative ::::::::::::::::::::::::::::::::: This is the only informative text block in this document. -These blocks can contain multiple paragraphs, tied together by lines containing just -">". +These blocks can contain multiple paragraphs, bulleted lists, etc. -These blocks can even contain tables! However, be wary of providing tables that are -too large in an Informative Text block. +These blocks can even contain tables! | Document Type | Informative Blocks | | ----------------- | ---------------------- | | SPECIFICATION | Usually | | GUIDANCE | Rarely | | REFERENCE | Rarely | -::::::::::::::::::: +::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: + +Strictly speaking, three colons (`:::`) are the minimum required for marking +an informative text block. However, it may make the plaintext version of the +doc easier to read. ### Other Informative Blocks @@ -515,13 +525,13 @@ Writers of a document may prefer "informative" blocks with more specific semantics. In this case, the text is still contained within a "TCG Informative" gray box, but with a more meaningful header. -::: Note ::: +:::::::::::::::::::::::::::::::::::: Note ::::::::::::::::::::::::::::::::::::: This is a "Note" block. -:::::::::::: +::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: -::: Example ::: +:::::::::::::::::::::::::::::::::: Example :::::::::::::::::::::::::::::::::::: This is an "Example" block. -::::::::::::::: +::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The behavior of blocks with labels not specified above may change meaningfully in future versions of this toolkit, so use them at your own risk. @@ -995,10 +1005,10 @@ documents in Markdown: of a "Final" styled document. Note that according to the rules of semver, 1.23.5 is higher than 1.23.5-rc.1. -::: Note ::: +:::::::::::::::::::::::::::::::::::: Note ::::::::::::::::::::::::::::::::::::: If the spec is not rendered as part of a release, it will always be a draft, of some revision on top of the latest released version. -:::::::::::: +::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ### Suppressing Git Version Parsing From 6a8edc78027e98dfeaed3e9b4d7fa653fa606952 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Mon, 5 Feb 2024 19:23:56 -0800 Subject: [PATCH 2/4] fix actions yaml --- .github/workflows/docker-publish.yml | 7 ++++++- .github/workflows/render-samples.yml | 7 ++++++- guide.md | 20 +++++++++----------- 3 files changed, 21 insertions(+), 13 deletions(-) diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index e842ccf..4cd69b9 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -120,7 +120,12 @@ jobs: env: cache-name: cache-latex-files with: - path: *.aux *.fdb_latexmk *.lof *.lot *.toc + path: | + *.aux + *.fdb_latexmk + *.lof + *.lot + *.toc key: latex - name: Render for release diff --git a/.github/workflows/render-samples.yml b/.github/workflows/render-samples.yml index 72b9056..cb7afd8 100644 --- a/.github/workflows/render-samples.yml +++ b/.github/workflows/render-samples.yml @@ -62,7 +62,12 @@ jobs: env: cache-name: cache-latex-files with: - path: *.aux *.fdb_latexmk *.lof *.lot *.toc + path: | + *.aux + *.fdb_latexmk + *.lof + *.lot + *.toc key: latex - name: Run the action on guide diff --git a/guide.md b/guide.md index bba3e21..5c0a819 100644 --- a/guide.md +++ b/guide.md @@ -109,7 +109,7 @@ a particular version of the tools and periodically update the tools as needed. A typical GitHub Markdown repo will: -* Render the spec to PDF and Word on pull requests and attach them to the PR. +* Render the spec to PDF on pull requests and attach the PDF to the PR. * Render the spec to PDF and Word on releases and attach them to the release. * Cache the LaTex intermediate files to the GitHub actions cache. This allows small changes to the doc to render faster. @@ -127,8 +127,8 @@ jobs: render: runs-on: ubuntu-latest container: - image: ghcr.io/trustedcomputinggroup/pandoc:0.8.2 - name: Render PDF + image: ghcr.io/trustedcomputinggroup/pandoc:0.9.10 + name: Render PDF and Word steps: - name: Checkout uses: actions/checkout@v3 @@ -141,7 +141,12 @@ jobs: env: cache-name: cache-latex-files with: - path: *.aux *.fdb_latexmk *.lof *.lot *.toc + path: | + *.aux + *.fdb_latexmk + *.lof + *.lot + *.toc key: latex - name: Render @@ -158,13 +163,6 @@ jobs: name: spec.pdf path: spec.pdf - - name: Upload Word to PR - uses: actions/upload-artifact@master - if: ${{ github.event_name == 'pull_request' }} - with: - name: spec.docx - path: spec.docx - - name: Upload PDF and docx to release uses: svenstaro/upload-release-action@v2 if: ${{ github.event_name == 'release' }} From 94b7bac2e83995e7cf47748e5892aaadec5b30c1 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Mon, 5 Feb 2024 19:27:28 -0800 Subject: [PATCH 3/4] ensure key is unique but also partially matched always --- .github/workflows/docker-publish.yml | 3 ++- .github/workflows/render-samples.yml | 3 ++- guide.md | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 4cd69b9..1714cd3 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -126,7 +126,8 @@ jobs: *.lof *.lot *.toc - key: latex + key: latex-${{ github.run_id }} + restore-keys: latex- - name: Render for release uses: trustedcomputinggroup/markdown@latest diff --git a/.github/workflows/render-samples.yml b/.github/workflows/render-samples.yml index cb7afd8..badd2b2 100644 --- a/.github/workflows/render-samples.yml +++ b/.github/workflows/render-samples.yml @@ -68,7 +68,8 @@ jobs: *.lof *.lot *.toc - key: latex + key: latex-${{ github.run_id }} + restore-keys: latex- - name: Run the action on guide uses: trustedcomputinggroup/markdown@latest diff --git a/guide.md b/guide.md index 5c0a819..b264cf1 100644 --- a/guide.md +++ b/guide.md @@ -147,7 +147,8 @@ jobs: *.lof *.lot *.toc - key: latex + key: latex-${{ github.run_id }} + restore-keys: latex- - name: Render uses: trustedcomputinggroup/markdown@v0.4.2 From 41a81066f0a9dcc16104a244111f5951f1d01140 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Mon, 5 Feb 2024 19:29:52 -0800 Subject: [PATCH 4/4] shorten restore key --- .github/workflows/docker-publish.yml | 2 +- .github/workflows/render-samples.yml | 2 +- guide.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 1714cd3..c6c4999 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -127,7 +127,7 @@ jobs: *.lot *.toc key: latex-${{ github.run_id }} - restore-keys: latex- + restore-keys: latex - name: Render for release uses: trustedcomputinggroup/markdown@latest diff --git a/.github/workflows/render-samples.yml b/.github/workflows/render-samples.yml index badd2b2..44de9f7 100644 --- a/.github/workflows/render-samples.yml +++ b/.github/workflows/render-samples.yml @@ -69,7 +69,7 @@ jobs: *.lot *.toc key: latex-${{ github.run_id }} - restore-keys: latex- + restore-keys: latex - name: Run the action on guide uses: trustedcomputinggroup/markdown@latest diff --git a/guide.md b/guide.md index b264cf1..fbee6c3 100644 --- a/guide.md +++ b/guide.md @@ -148,7 +148,7 @@ jobs: *.lot *.toc key: latex-${{ github.run_id }} - restore-keys: latex- + restore-keys: latex - name: Render uses: trustedcomputinggroup/markdown@v0.4.2