diff --git a/.github/workflows/actions.yml b/.github/workflows/actions.yml deleted file mode 100644 index b66abd6..0000000 --- a/.github/workflows/actions.yml +++ /dev/null @@ -1,44 +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.8.1 - name: Render PDF - steps: - - name: Checkout - uses: actions/checkout@v3 - - - 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 - - - name: Upload PDF to PR - uses: actions/upload-artifact@master - if: ${{ github.event_name == 'pull_request' }} - with: - name: spec - path: spec.pdf - - - name: Upload PDF and docx to release - uses: svenstaro/upload-release-action@v2 - if: ${{ github.event_name == 'release' }} - with: - repo_token: ${{ secrets.GITHUB_TOKEN }} - file: spec.* - 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.md b/document.tcg similarity index 62% rename from spec.md rename to document.tcg index 521db6e..95bb3ce 100644 --- a/spec.md +++ 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 @@ -68,17 +73,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. +:::::::::::::::::::: --- @@ -89,3 +86,27 @@ 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 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 `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 . +* (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