From 9af4ffa972dbb19a7cc613a5d5f5bd038a076eab Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Tue, 30 Jan 2024 21:17:52 +0000 Subject: [PATCH 1/6] update instructions and pandoc version --- .github/workflows/actions.yml | 3 +-- spec.md | 36 ++++++++++++++++++++++++++--------- 2 files changed, 28 insertions(+), 11 deletions(-) diff --git a/.github/workflows/actions.yml b/.github/workflows/actions.yml index b66abd6..eb807f8 100644 --- a/.github/workflows/actions.yml +++ b/.github/workflows/actions.yml @@ -12,7 +12,7 @@ jobs: render: runs-on: ubuntu-latest container: - image: ghcr.io/trustedcomputinggroup/pandoc:0.8.1 + image: ghcr.io/trustedcomputinggroup/pandoc:0.8.2 name: Render PDF steps: - name: Checkout @@ -21,7 +21,6 @@ jobs: - name: Render uses: trustedcomputinggroup/markdown@v0.4.2 with: - extra-build-options: "--gitstatus --plain_quotes" input-md: spec.md output-pdf: spec.pdf output-docx: spec.docx diff --git a/spec.md b/spec.md index 521db6e..2f64d51 100644 --- a/spec.md +++ b/spec.md @@ -69,15 +69,15 @@ comment_, it can be considered a _normative statement_. EXAMPLE: ::: Informative ::: -> This is the first paragraph of 1–n paragraphs containing text of the kind -> informative comment ... -> -> This is the second paragraph of text of the kind informative comment ... -> -> This is the nth paragraph of text of the kind informative comment ... -> -> To understand the TCG specification, the user must read the specification. -> (This use of MUST does not require any action). +This is the first paragraph of 1–n paragraphs containing text of the kind +informative comment ... + +This is the second paragraph of text of the kind informative comment ... + +This is the nth paragraph of text of the kind informative comment ... + +To understand the TCG specification, the user must read the specification. +(This use of MUST does not require any action). ::::::::::::::::::: --- @@ -89,3 +89,21 @@ EXAMPLE: \listoftables --- + +# Checklist for users of this template + +* Ensure the repository is set to private +* Add the correct GitHub team(s) to Collaborators* Add TCGadmin to Admin +* Add a branch protection rule on `main` + * Require a pull request before merging + * Require approvals + * Do not allow bypassing the above settings + * (Optional) Require review from Code Owners (Requires setting up CODEOWNERS file) +* (Optional) rename spec.md and update all references in `actions.yml` +* Check for newer [pandoc](https://github.com/trustedcomputinggroup/pandoc) and + [markdown](https://github.com/trustedcomputinggroup/markdown) action versions + for `actions.yml` +* Update the document title and type in the YAML front matter + * For GUIDANCE or REFERENCE docs, add `template: bluetop` +* (Optional) Do an initial release to set baseline version (e.g., if migrating + from an existing Word doc). \ No newline at end of file From d639db2c5beec0358e1008c05cde9b9b11bac838 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Wed, 31 Jan 2024 16:05:41 +0000 Subject: [PATCH 2/6] suggest docx uploads for prs --- .github/workflows/actions.yml | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/.github/workflows/actions.yml b/.github/workflows/actions.yml index eb807f8..0d02ea0 100644 --- a/.github/workflows/actions.yml +++ b/.github/workflows/actions.yml @@ -29,9 +29,16 @@ jobs: uses: actions/upload-artifact@master if: ${{ github.event_name == 'pull_request' }} with: - name: spec + 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 55dfc3553b4fdea618fa4edbb821c616e3c6bc9e Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Mon, 12 Feb 2024 19:10:31 +0000 Subject: [PATCH 3/6] update latest pandoc and spec guidance --- .github/workflows/actions.yml | 43 +++++++++++++++++++++++++++++------ spec.md | 22 +++++++----------- 2 files changed, 44 insertions(+), 21 deletions(-) diff --git a/.github/workflows/actions.yml b/.github/workflows/actions.yml index 0d02ea0..766109b 100644 --- a/.github/workflows/actions.yml +++ b/.github/workflows/actions.yml @@ -12,16 +12,35 @@ jobs: render: runs-on: ubuntu-latest container: - image: ghcr.io/trustedcomputinggroup/pandoc:0.8.2 + image: ghcr.io/trustedcomputinggroup/pandoc:0.10.2 name: Render PDF 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 + *.convert.pdf + key: latex-${{ github.run_id }} + restore-keys: latex - name: Render uses: trustedcomputinggroup/markdown@v0.4.2 with: input-md: spec.md + extra-build-options: "--versioned_filenames" output-pdf: spec.pdf output-docx: spec.docx @@ -29,22 +48,32 @@ jobs: uses: actions/upload-artifact@master if: ${{ github.event_name == 'pull_request' }} with: - name: spec.pdf - path: spec.pdf + name: 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: Word + path: spec.*.docx + + - name: Upload PDF to release + uses: svenstaro/upload-release-action@v2 + if: ${{ github.event_name == 'release' }} + with: + repo_token: ${{ secrets.GITHUB_TOKEN }} + file: spec.*.pdf + tag: ${{ github.ref }} + overwrite: true + file_glob: true - - name: Upload PDF and docx to release + - name: Upload Word to release uses: svenstaro/upload-release-action@v2 if: ${{ github.event_name == 'release' }} with: repo_token: ${{ secrets.GITHUB_TOKEN }} - file: spec.* + file: spec.*.docx tag: ${{ github.ref }} overwrite: true file_glob: true diff --git a/spec.md b/spec.md index 2f64d51..232a19a 100644 --- a/spec.md +++ b/spec.md @@ -68,17 +68,9 @@ comment_, it can be considered a _normative statement_. EXAMPLE: -::: Informative ::: -This is the first paragraph of 1–n paragraphs containing text of the kind -informative comment ... - -This is the second paragraph of text of the kind informative comment ... - -This is the nth paragraph of text of the kind informative comment ... - -To understand the TCG specification, the user must read the specification. -(This use of MUST does not require any action). -::::::::::::::::::: +::: Informative :::: +Reach out to with any questions about this document. +:::::::::::::::::::: --- @@ -93,7 +85,8 @@ To understand the TCG specification, the user must read the specification. # Checklist for users of this template * Ensure the repository is set to private -* Add the correct GitHub team(s) to Collaborators* Add TCGadmin to Admin +* Add the correct GitHub team(s) to Collaborators +* Add TCGadmin to Admin * Add a branch protection rule on `main` * Require a pull request before merging * Require approvals @@ -104,6 +97,7 @@ To understand the TCG specification, the user must read the specification. [markdown](https://github.com/trustedcomputinggroup/markdown) action versions for `actions.yml` * Update the document title and type in the YAML front matter - * For GUIDANCE or REFERENCE docs, add `template: bluetop` * (Optional) Do an initial release to set baseline version (e.g., if migrating - from an existing Word doc). \ No newline at end of file + from an existing Word doc). +* (Optional) Review the guidance about release naming in the latest User's + Guide from . \ No newline at end of file From 9ff3191a19ab3426e33926f633ee43cb3cff8684 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Mon, 12 Feb 2024 19:11:04 +0000 Subject: [PATCH 4/6] rename spec.tcg --- .github/workflows/actions.yml | 2 +- spec.md => spec.tcg | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename spec.md => spec.tcg (100%) diff --git a/.github/workflows/actions.yml b/.github/workflows/actions.yml index 766109b..204fc5a 100644 --- a/.github/workflows/actions.yml +++ b/.github/workflows/actions.yml @@ -39,7 +39,7 @@ jobs: - name: Render uses: trustedcomputinggroup/markdown@v0.4.2 with: - input-md: spec.md + input-md: spec.tcg extra-build-options: "--versioned_filenames" output-pdf: spec.pdf output-docx: spec.docx diff --git a/spec.md b/spec.tcg similarity index 100% rename from spec.md rename to spec.tcg From 1fe443d95749c4605a066f889b0629a642468dbd Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Wed, 19 Nov 2025 09:47:00 -0800 Subject: [PATCH 5/6] modernize the actions and add citation boilerplate --- .github/workflows/actions.yml | 79 ------ .github/workflows/manual.yml | 23 ++ .github/workflows/pr.yml | 12 + .github/workflows/push.yml | 14 + .github/workflows/release.yml | 12 + .github/workflows/render.yml | 36 +++ bibliography.yml | 8 + spec.tcg => document.tcg | 25 +- ieee.csl | 512 ++++++++++++++++++++++++++++++++++ 9 files changed, 634 insertions(+), 87 deletions(-) delete mode 100644 .github/workflows/actions.yml create mode 100644 .github/workflows/manual.yml create mode 100644 .github/workflows/pr.yml create mode 100644 .github/workflows/push.yml create mode 100644 .github/workflows/release.yml create mode 100644 .github/workflows/render.yml create mode 100644 bibliography.yml rename spec.tcg => document.tcg (80%) create mode 100644 ieee.csl diff --git a/.github/workflows/actions.yml b/.github/workflows/actions.yml deleted file mode 100644 index 204fc5a..0000000 --- a/.github/workflows/actions.yml +++ /dev/null @@ -1,79 +0,0 @@ -# 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: - types: [published] - -jobs: - render: - runs-on: ubuntu-latest - container: - image: ghcr.io/trustedcomputinggroup/pandoc:0.10.2 - name: Render PDF - 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 - *.convert.pdf - key: latex-${{ github.run_id }} - restore-keys: latex - - - name: Render - uses: trustedcomputinggroup/markdown@v0.4.2 - with: - input-md: spec.tcg - extra-build-options: "--versioned_filenames" - output-pdf: spec.pdf - output-docx: spec.docx - - - name: Upload PDF to PR - uses: actions/upload-artifact@master - if: ${{ github.event_name == 'pull_request' }} - with: - name: PDF - path: spec.*.pdf - - - name: Upload Word to PR - uses: actions/upload-artifact@master - if: ${{ github.event_name == 'pull_request' }} - with: - name: Word - path: spec.*.docx - - - name: Upload PDF to release - uses: svenstaro/upload-release-action@v2 - if: ${{ github.event_name == 'release' }} - with: - repo_token: ${{ secrets.GITHUB_TOKEN }} - file: spec.*.pdf - tag: ${{ github.ref }} - overwrite: true - file_glob: true - - - name: Upload Word to release - uses: svenstaro/upload-release-action@v2 - if: ${{ github.event_name == 'release' }} - with: - repo_token: ${{ secrets.GITHUB_TOKEN }} - file: spec.*.docx - tag: ${{ github.ref }} - overwrite: true - file_glob: true diff --git a/.github/workflows/manual.yml b/.github/workflows/manual.yml new file mode 100644 index 0000000..d5868f9 --- /dev/null +++ b/.github/workflows/manual.yml @@ -0,0 +1,23 @@ +# Render the document on-demand. This can be useful for producing one-off diffs. + +name: Render (Manual) + +on: + workflow_dispatch: + inputs: + revision: + description: the version or commit to render (if left empty, uses default branch) + required: false + type: string + diffbase: + description: the version or commit to diff against (if left empty, no diff is generated) + required: false + type: string + +jobs: + render: + uses: ./.github/workflows/render.yml + with: + workflow: manual + revision: ${{ inputs.revision }} + manual_diffbase: ${{ inputs.diffbase }} diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml new file mode 100644 index 0000000..eab4eb9 --- /dev/null +++ b/.github/workflows/pr.yml @@ -0,0 +1,12 @@ +# Render the document on pull requests. + +name: Render (Pull Request) + +on: + pull_request: + +jobs: + render: + uses: ./.github/workflows/render.yml + with: + workflow: pr diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml new file mode 100644 index 0000000..dd86f11 --- /dev/null +++ b/.github/workflows/push.yml @@ -0,0 +1,14 @@ +# Render the document on pushes to main. + +name: Render (Push) + +on: + push: + branches: + - main + +jobs: + render-all-parts: + uses: ./.github/workflows/render.yml + with: + workflow: push diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..d5b9f3d --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,12 @@ +# Render the document on releases. + +name: Render (Release) + +on: + release: + +jobs: + render-all-parts: + uses: ./.github/workflows/render.yml + with: + workflow: release diff --git a/.github/workflows/render.yml b/.github/workflows/render.yml new file mode 100644 index 0000000..fff516a --- /dev/null +++ b/.github/workflows/render.yml @@ -0,0 +1,36 @@ +# Reusable workflow to render the spec. +# https://docs.github.com/en/actions/using-workflows/reusing-workflows + +name: Render + +on: + workflow_call: + inputs: + workflow: + description: the workflow to run ('pr', 'push', 'release', 'manual') + required: true + type: string + revision: + description: version to render (default is default branch) + required: false + type: string + manual_diffbase: + description: diffbase for manual workflow + required: false + type: string + +jobs: + render: + # When updating the version of the Pandoc toolset, update the + # container-version below as well. + uses: trustedcomputinggroup/pandoc/.github/workflows/render.yml@v0.18.14 + with: + container-version: 0.18.14 + # When renaming the file in the repository, change it here as well. + # For a project containing multiple parts, it may be useful to create + # a "render all" reusable workflow that passes each file to this workflow + # as an additional "input" parameter. + input: document.tcg + workflow: ${{ inputs.workflow }} + revision: ${{ inputs.revision }} + manual_diffbase: ${{ inputs.manual_diffbase }} diff --git a/bibliography.yml b/bibliography.yml new file mode 100644 index 0000000..bb9dbc2 --- /dev/null +++ b/bibliography.yml @@ -0,0 +1,8 @@ +references: + - id: "alg-registry" + title: "TCG Algorithm Registry" + publisher: "Trusted Computing Group" + issued: + year: 2025 + month: 2 + url: "https://trustedcomputinggroup.org/resource/tcg-algorithm-registry/" diff --git a/spec.tcg b/document.tcg similarity index 80% rename from spec.tcg rename to document.tcg index 232a19a..75b5ef4 100644 --- a/spec.tcg +++ b/document.tcg @@ -1,24 +1,26 @@ --- title: "Document Title" type: SPECIFICATION +bibliography: bibliography.yml +csl: ieee.csl ... --- # Disclaimers, Notices, and License Terms -THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO WARRANTIES WHATSOEVER, INCLUDING +THIS DOCUMENT IS PROVIDED "AS IS" WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR ANY PARTICULAR -PURPOSE, OR ANY WARRANTY OTHERWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR +PURPOSE, OR ANY WARRANTY OTHERWISE ARISING OUT OF ANY PROPOSAL, DOCUMENT OR SAMPLE. Without limitation, TCG disclaims all liability, including liability for infringement of any proprietary rights, relating to use of information in this -specification and to the implementation of this specification, and TCG disclaims +document and to the implementation of this document, and TCG disclaims all liability for cost of procurement of substitute goods or services, lost profits, loss of use, loss of data or any incidental, consequential, direct, indirect, or special damages, whether under contract, tort, warranty or -otherwise, arising in any way out of use or reliance upon this specification or +otherwise, arising in any way out of use or reliance upon this document or any information herein. This document is copyrighted by Trusted Computing Group (TCG), and no license, @@ -43,6 +45,9 @@ owners. **Version** **Date** **Description** ----------- ---------- --------------------------------------------------------- 0.1 2024/01/29 Initial draft +----------- ---------- --------------------------------------------------------- +1.0 2025/11/19 Streamlined GitHub actions and included IEEE citation + boilerplate files. -------------------------------------------------------------------------------- # Document Style @@ -92,12 +97,16 @@ Reach out to with any questions about this documen * Require approvals * Do not allow bypassing the above settings * (Optional) Require review from Code Owners (Requires setting up CODEOWNERS file) -* (Optional) rename spec.md and update all references in `actions.yml` +* (Optional) rename document.md and update all references in `render.yml` * Check for newer [pandoc](https://github.com/trustedcomputinggroup/pandoc) and [markdown](https://github.com/trustedcomputinggroup/markdown) action versions - for `actions.yml` -* Update the document title and type in the YAML front matter + for `render.yml` +* Update the document title and type (SPECIFICATION, GUIDANCE, or REFERENCE) in + the YAML front matter * (Optional) Do an initial release to set baseline version (e.g., if migrating from an existing Word doc). * (Optional) Review the guidance about release naming in the latest User's - Guide from . \ No newline at end of file + Guide from . +* (Optional) Customize the citation style if IEEE is not preferred. +* (Optional) For a document with no references, remove the `bibliography` and + `csl` from the YAML front matter instead. diff --git a/ieee.csl b/ieee.csl new file mode 100644 index 0000000..419f170 --- /dev/null +++ b/ieee.csl @@ -0,0 +1,512 @@ + + \ No newline at end of file From 78c5c79fc81c8628316882aa933c89477832bf29 Mon Sep 17 00:00:00 2001 From: Chris Fenner Date: Wed, 19 Nov 2025 09:52:02 -0800 Subject: [PATCH 6/6] fix table --- document.tcg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/document.tcg b/document.tcg index 75b5ef4..95bb3ce 100644 --- a/document.tcg +++ b/document.tcg @@ -45,7 +45,7 @@ owners. **Version** **Date** **Description** ----------- ---------- --------------------------------------------------------- 0.1 2024/01/29 Initial draft ------------ ---------- --------------------------------------------------------- + 1.0 2025/11/19 Streamlined GitHub actions and included IEEE citation boilerplate files. --------------------------------------------------------------------------------