From abbe5d4331159c11b92035158183dd242f656ceb Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Mon, 2 Sep 2024 15:56:31 +0100 Subject: [PATCH 01/12] Updated CI for v3.0.1 publication and new spec-parser Signed-off-by: Arthit Suriyawongkul --- .github/workflows/publish_v3.yml | 135 +++++++++++++++----- .github/workflows/validate_pull_request.yml | 51 ++------ .gitignore | 8 +- README.md | 63 +++++---- mkdocs.yml | 18 ++- requirements.txt | 6 +- 6 files changed, 167 insertions(+), 114 deletions(-) diff --git a/.github/workflows/publish_v3.yml b/.github/workflows/publish_v3.yml index 55d2658d64..4315c9fb20 100644 --- a/.github/workflows/publish_v3.yml +++ b/.github/workflows/publish_v3.yml @@ -10,67 +10,134 @@ jobs: build: runs-on: ubuntu-latest container: python:3 + env: + PARSER_OUTPUT_DIR: "__parser_output" # temp dir for output from spec-parser + RDF_BASE_DIR: "" # change to "rdf" in new structure + MKDOCS_BASE_DIR: "" # change to "mkdocs" in new structure + MKDOCS_MODEL_YML: "mkdocs-files.yml" # contains list of model Markdown files + BASE_MKDOCS_YML: "mkdocs.yml" # initial MkDocs configuration + FULL_MKDOCS_YML: "__mkdocs-full.yml" # MkDocs configuration combined with model list + GIT_USER_NAME: "ci-bot" # for gh-pages commit + GIT_USER_EMAIL: "ci-bot@spdx.dev" # for gh-pages commit steps: - - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 + - name: Checkout spdx-spec + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 with: ref: development/v3.0.1 path: spdx-spec fetch-depth: 0 # Because we will be pushing the gh-pages branch - - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 - with: - repository: spdx/spec-parser - ref: main - path: spec-parser - - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 + - name: Checkout spdx-3-model + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 with: repository: spdx/spdx-3-model ref: main # for v3.0.1-draft, checkout latest from main (development) # Once 3.0.1 released, use the following ref to checkout from the release tag # ref: 3.0.1 # for v3.0.1 final release path: spdx-3-model + - name: Checkout spec-parser + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 + with: + repository: spdx/spec-parser + ref: main + path: spec-parser - name: Install pre-requisites for spdx-spec run: pip install -r spdx-spec/requirements.txt - name: Install pre-requisites for spec-parser run: pip install -r spec-parser/requirements.txt - name: Build model files - run: python3 spec-parser/main.py spdx-3-model/model spdx-spec/docs/model + run: python3 spec-parser/main.py spdx-3-model/model $PARSER_OUTPUT_DIR + - name: Create directories for model (MkDocs) and RDF files + run: | + mkdir spdx-spec/docs/rdf + mkdir spdx-spec/docs/model - name: Copy JSON annotations - run: cp spdx-spec/serialization/jsonld/annotations.ttl spdx-spec/docs/model/jsonld-annotations.ttl - - name: Generate JSON schema + # Will be redirected from https://spdx.org/rdf/3.0.0/spdx-json-serialize-annotations.ttl + # and available at https://spdx.github.io/spdx-spec/v3.0/rdf/jsonld-annotations.ttl + run: | + cp spdx-spec/serialization/jsonld/annotations.ttl spdx-spec/docs/rdf/jsonld-annotations.ttl + cp spdx-spec/serialization/jsonld/annotations.ttl spdx-spec/docs/model/jsonld-annotations.ttl + - name: Copy JSON-LD context and RDFs + # Will be redirected from https://spdx.org/rdf/3.0.0/spdx-context.jsonld, spdx-model.ttl, etc. + # and available at https://spdx.github.io/spdx-spec/v3.0/model/spdx-context.jsonld + run: | + echo "=====================" + echo "Source: $PARSER_OUTPUT_DIR/$RDF_BASE_DIR" + echo "---------------------" + ls $PARSER_OUTPUT_DIR/$RDF_BASE_DIR + echo "=====================" + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-context.jsonld spdx-spec/docs/rdf/ + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.dot spdx-spec/docs/rdf/ + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.json-ld spdx-spec/docs/rdf/ + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.pretty-xml spdx-spec/docs/rdf/ + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.ttl spdx-spec/docs/rdf/ + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.xml spdx-spec/docs/rdf/ + cp spdx-spec/docs/rdf/spdx-model.json-ld spdx-spec/docs/rdf/spdx-model.jsonld + echo "=====================" + echo "Target (after copy): spdx-spec/docs/rdf" + echo "---------------------" + ls spdx-spec/docs/rdf + echo "=====================" + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-context.jsonld spdx-spec/docs/model/ + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.dot spdx-spec/docs/model/ + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.json-ld spdx-spec/docs/model/ + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.pretty-xml spdx-spec/docs/model/ + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.ttl spdx-spec/docs/model/ + cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.xml spdx-spec/docs/model/ + cp spdx-spec/docs/model/spdx-model.json-ld spdx-spec/docs/model/spdx-model.jsonld + echo "=====================" + echo "Target (after copy): spdx-spec/docs/model" + echo "---------------------" + ls spdx-spec/docs/model + echo "=====================" + - name: Generate JSON schema -- OLD DIR STRUCTURE + # Will be redirected from https://spdx.org/schema/3.0.0/spdx-json-schema.json + # and available at https://spdx.github.io/spdx-spec/v3.0/model/schema.json run: | shacl2code generate \ - --input spdx-spec/docs/model/spdx-model.ttl \ - --input spdx-spec/docs/model/jsonld-annotations.ttl \ - --context-url spdx-spec/docs/model/spdx-context.jsonld https://spdx.org/rdf/3.0.1/spdx-context.jsonld \ + --input spdx-spec/docs/rdf/spdx-model.ttl \ + --input spdx-spec/docs/rdf/jsonld-annotations.ttl \ + --context-url spdx-spec/docs/rdf/spdx-context.jsonld https://spdx.org/rdf/3.0.1/spdx-context.jsonld \ jsonschema \ - --output spdx-spec/docs/model/schema.json - - name: Set git identity + --output spdx-spec/docs/rdf/schema.json + cp spdx-spec/docs/rdf/schema.json spdx-spec/docs/model/schema.json + - name: Copy model files and file list for MkDocs + # Will be available at https://spdx.github.io/spdx-spec/v3.0/model/* + run: | + cp -R $PARSER_OUTPUT_DIR/$MKDOCS_BASE_DIR/* spdx-spec/docs/model + cp $PARSER_OUTPUT_DIR/$MKDOCS_MODEL_YML spdx-spec + - name: Set Git identity working-directory: spdx-spec - run: git config user.name ci-bot; git config user.email ci-bot@spdx.dev + run: git config user.name $GIT_USER_NAME; git config user.email $GIT_USER_EMAIL - name: Sync gh-pages working-directory: spdx-spec run: git checkout gh-pages && git pull && git checkout development/v3.0.1 - - name: Build docs and set aliases + - name: Build complete MkDocs configuration working-directory: spdx-spec run: | - MODEL_YML="docs/model/mkdocs-files.yml" - BASE_MKDOCS_YML="mkdocs.yml" - FINAL_MKDOCS_YML="mkdocs-final.yml" - echo "Build $FINAL_MKDOCS_YML from $BASE_MKDOCS_YML and $MODEL_YML" - sed -e "\|- model.*#.*[MODEL_PLACEHOLDER].*|{ - r $MODEL_YML + echo "Build $FULL_MKDOCS_YML from $BASE_MKDOCS_YML and $MKDOCS_MODEL_YML" + sed -e "\|- model.*#.*__MODEL_PLACEHOLDER__.*|{ + r $MKDOCS_MODEL_YML a\\ d - }" "$BASE_MKDOCS_YML" > "$FINAL_MKDOCS_YML" - echo "=====================" - echo "Start mike deploy" + }" "$BASE_MKDOCS_YML" > "$FULL_MKDOCS_YML" + sed -i "/__MODEL_PLACEHOLDER__/d" "$FULL_MKDOCS_YML" echo "=====================" - mike deploy --update-aliase --config-file "$FINAL_MKDOCS_YML" --branch gh-pages --push v3.0.1-draft - # Once 3.0.1 released, use the following command to deploy 3.0.1 as latest version - # mike deploy --update-aliase --config-file "$FINAL_MKDOCS_YML" --branch gh-pages --push v3.0.1 latest -# - name: Set default version -# working-directory: spdx-spec -# run: mike set-default v3.0 - # Once 3.0.1 released, use the following command to set 3.0.1 as default version - # run: mike set-default v3.0.1 + echo "$FULL_MKDOCS_YML" + echo "---------------------" + cat "$FULL_MKDOCS_YML" + echo "[End of File]" + - name: Deploy and set aliases + working-directory: spdx-spec + run: | + mike delete --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push --allow-empty v3.0 || true + mike delete --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push --allow-empty v3.0.1-draft || true + mike deploy --update-aliase --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push v3.0.1 v3.0.1-draft v3-draft v3.0-RC1 v3.0-RC2 v3.0 latest + mike set-default --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push v3.0.1 + # Explanations of the above mike steps: + # 1) delete existing v3.0 alias/deployment, if exists + # 2) delete existing v3.0.1-draft alias/deployment, if exists + # 3) deploy v3.0.1, with aliases (v3.0.1-draft, v3-draft, v3.0-RC1, v3.0-RC2, v3.0 latest) + # 4) set default version to v3.0.1 + # A script for additional redirections will be run after this point + # See https://github.com/spdx/spdx-spec/issues/1069 diff --git a/.github/workflows/validate_pull_request.yml b/.github/workflows/validate_pull_request.yml index 02a4f49ab5..264be233bf 100644 --- a/.github/workflows/validate_pull_request.yml +++ b/.github/workflows/validate_pull_request.yml @@ -6,44 +6,13 @@ jobs: runs-on: ubuntu-latest container: python:3 steps: - - name: Checkout spdx-spec - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 - with: - path: spdx-spec - fetch-depth: 1 - - name: Checkout spdx-3-model - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 - with: - repository: spdx/spdx-3-model - ref: main - path: spdx-3-model - - name: Checkout spec-parser - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 - with: - repository: spdx/spec-parser - ref: main - path: spec-parser - - name: Install pre-requisites for spdx-spec - run: pip install -r spdx-spec/requirements.txt - - name: Install pre-requisites for spec-parser - run: pip install -r spec-parser/requirements.txt - - name: Build model files - run: python3 spec-parser/main.py spdx-3-model/model spdx-spec/docs/model - - name: Build the site to validate - working-directory: spdx-spec - run: | - MODEL_YML="docs/model/mkdocs-files.yml" - BASE_MKDOCS_YML="mkdocs.yml" - FINAL_MKDOCS_YML="mkdocs-final.yml" - echo "Build $FINAL_MKDOCS_YML from $BASE_MKDOCS_YML and $MODEL_YML" - sed -e "\|- model.*#.*[MODEL_PLACEHOLDER].*|{ - r $MODEL_YML - a\\ - - d - }" "$BASE_MKDOCS_YML" > "$FINAL_MKDOCS_YML" - echo "=====================" - echo "Start mkdocs build" - echo "=====================" - ENABLE_PDF_EXPORT=0 mkdocs build --clean --config-file "$FINAL_MKDOCS_YML" --verbose - # Build without the time-consuming PDF export + - name: Checkout spdx-spec + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 + with: + fetch-depth: 1 + - name: Install pre-requisites + run: pip install -r requirements.txt + - name: Build the site to validate (use mkdocs.yml, no model files, no PDF export) + run: ENABLE_PDF_EXPORT=0 mkdocs build --clean --verbose + # To validate the PR from within spdx-spec repo, build using mkdocs.yml + # (no model files) and without the time-consuming PDF export diff --git a/.gitignore b/.gitignore index 5888a4ce1f..88db66e613 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,7 @@ _book/ dist/ site/ -# Ignore all hidden files/dirs except .gitignore +# Ignore all hidden files/dirs except .gitignore and .github .* !/.gitignore !/.github @@ -28,3 +28,9 @@ node_modules/ Thumbs.db Thumbs.db:encryptable *.lnk + +# Build temporary directory +.env +logs/ +__pycache__/ +__mkdocs-full.yml diff --git a/README.md b/README.md index a1e6d47e67..5b7879dc8a 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,8 @@ This repository holds under active development version of the specification as: - HTML: `gh-pages` branch, built on every commit to the development branch, see the workflow in [`.github/workflows/publish_v3.yml`](.github/workflows/publish_v3.yml) - - Current (3.0): + - Current stable (v3.0.1): + The model itself is under active development at [spdx/spdx-3-model](https://github.com/spdx/spdx-3-model/) @@ -29,6 +30,16 @@ See for the official [releases of the specification](https://spdx.org/specifications) or additional information also the SPDX website at . +Information on how to use the SPDX specification is available at +[spdx/using](https://github.com/spdx/using/) repo. +Demonstrations of SPDX for various scenarios and use cases are available at +[spdx/spdx-examples](https://github.com/spdx/spdx-examples). + +See [change log](./CHANGELOG.md) for changes between versions. +Contributions are welcome, +please see the [contributing guidelines](./CONTRIBUTING.md) +and [governance practices](https://github.com/spdx/governance/). + ## Specification structure This repository consists of these files and directories: @@ -42,7 +53,7 @@ This repository consists of these files and directories: [model.drawio](https://github.com/spdx/spdx-3-model/blob/main/model.drawio) in `spdx/spdx-3-model` repo and manually copied here. - `licenses/` - Licenses that used by the SPDX specifications. - - `model/` - Model files*. This subdirectory _is to be created_ by a script + - `model/` - Model files. This subdirectory _is to be created_ by a script from `spdx/spec-parser` repo, using model information from `spdx/spdx-3-model` repo (see the build instructions below). - `examples/` - Examples of various SPDX serializations for the current version @@ -105,13 +116,8 @@ installed on your machine. If you don't have it yet installed please follow these [installation instructions](http://www.mkdocs.org/#installation). [WeasyPrint](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation) -is also required for generating PDF files. To disable PDF generation, comment -out the these lines in your `mkdocs.yml` configuration file: - -```yaml -#- pdf-export: -# combined: true -``` +is also required for generating PDF files. To enable PDF generation, set the +`ENABLE_PDF_EXPORT` environment variable to `1`. ### Preparing input files @@ -135,7 +141,7 @@ pip3 install -r spdx-spec/requirements.txt pip3 install -r spec-parser/requirements.txt ``` -### Generating formatted Markdown files for MkDocs +### Generating model and formatted Markdown files for MkDocs Model files in `spdx/spdx-3-model` repo are written in a specific format of Markdown, with a limited set of allowed headings. The `spec-parser` processes @@ -179,36 +185,37 @@ into a website. In side `spdx-spec/` directory, execute a built-in dev-server that let you preview the specification: -```shell -mkdocs serve -``` +These following commands should run inside the `spdx-spec/` directory. -Or building a static HTML site: +- To preview the specification in a web browser: -```shell -mkdocs build -``` + ```shell + mkdocs serve + ``` -To abort the build immediately when there is a warning, enables strict mode: +- To build a static HTML site: -```shell -mkdocs build --strict -``` + ```shell + mkdocs build + ``` -To get debug messages, enables verbose output: +- To get debug messages, enables verbose output: -```shell -mkdocs build --verbose -``` + ```shell + mkdocs build --verbose + ``` ## Configuring the website Inside `spdx-spec/` directory, there is a file `mkdocs.yml`. This is a configuration file for MkDocs. -Files intended for display and linking in the navigation bar should be -included in the `nav:` section. The order of filenames in this section -determines their order on the navigation bar. +You can customize website details like the site name and main URL (canonical +URL) in this file. + +To include a page in the navigation bar, list its filename under the `nav:` +section. The order of filenames in this section determines the order of the +page in the navigation bar. ## Specification versions on spdx.github.io/spdx-spec/ diff --git a/mkdocs.yml b/mkdocs.yml index 52bd46a3d9..47404eea76 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,16 +1,19 @@ -site_name: SPDX v3 Specification -site_description: The System Package Data Exchange (SPDX) Specification Version 3.0.1 +site_name: SPDX Specification 3.0.1 +site_description: The System Package Data Exchange (SPDX) Specification Version 3.0.1 - Open standard for creating Software Bills of Materials (SBOMs) site_author: The Linux Foundation and its Contributors, including SPDX Model contributions from OMG and its Contributors. -site_url: https://spdx.github.io/spdx-spec/ +site_url: https://spdx.github.io/spdx-spec/ # set to the "root" of the site, to be combined with canonical_version repo_url: https://github.com/spdx/spdx-spec/ edit_uri: "" # set to an empty string to disable edit links; to enable, set to blob/development/v3.0.1/docs/ copyright: SPDX v3.0.1 Copyright © 2010-2024, The Linux Foundation and its Contributors, including SPDX Model contributions from OMG and its Contributors. use_directory_urls: true -theme: readthedocs +theme: + name: readthedocs + sticky_navigation: true plugins: - search - mike: - canonical_version: v3.0.1 # tell search engines to prefer the latest version + canonical_version: v3.0.1 # tell search engines to prefer the URL of v3.0.1 + alias_type: redirect # use redirect so it can redirect every pages (not just the root of the version) - pdf-export: combined: true media_type: print @@ -23,7 +26,7 @@ markdown_extensions: strict: true validation: nav: - omitted_files: info # allow during development where there are moving parts + omitted_files: warn # use "info" to relax during development where there are moving parts not_found: warn # warn if a file is referenced in the nav but not included in the build absolute_links: warn links: @@ -40,7 +43,8 @@ nav: - '4. Terms and definitions': terms-and-definitions.md - '5. Conformance': conformance.md - '6. Model and serializations': serializations.md -- model: # [MODEL_PLACEHOLDER], to be replaced by content from mkdocs-files.yml +- model: # __MODEL_PLACEHOLDER__, to be replaced by content from mkdocs-files.yml + - "__MODEL_PLACEHOLDER__": "https://example.com" # allows mkdocs.yml to be build/tested without full model list - annexes: - 'A. Changes from the previous standard': annexes/changes-from-previous-iso.md - 'B. RDF model definition and diagrams': annexes/rdf-model.md diff --git a/requirements.txt b/requirements.txt index 62fa549c57..6aff8f8296 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ json-schema-for-humans==1.0.2 -mike==2.1.2 -mkdocs==1.6.0 +mike==2.1.3 +mkdocs==1.6.1 mkdocs-pdf-export-plugin==0.5.10 -PyYAML==6.0.1 +PyYAML==6.0.2 shacl2code==0.0.13 From cccb11f2a812c4070011a30773ef32910d9fa912 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Mon, 2 Sep 2024 16:31:50 +0100 Subject: [PATCH 02/12] Use environment variables to set branch/tag release Signed-off-by: Arthit Suriyawongkul --- .github/workflows/publish.yml | 66 ---------------------------- .github/workflows/publish_common.yml | 35 --------------- .github/workflows/publish_v3.yml | 22 +++++----- 3 files changed, 12 insertions(+), 111 deletions(-) delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_common.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml deleted file mode 100644 index 672221963f..0000000000 --- a/.github/workflows/publish.yml +++ /dev/null @@ -1,66 +0,0 @@ -on: - push: - branches: [master, development/v2.3] - -jobs: - build_current: - name: Build current - if: github.ref == 'refs/heads/master' - runs-on: ubuntu-latest - container: python:3 - steps: - - uses: actions/checkout@v2 - with: - ref: 'master' - - name: Install pre-requisites - run: pip install -r requirements.txt - - name: Build - run: mkdocs build -v --clean - - name: Schema - run: generate-schema-doc schemas/spdx-schema.json site/spdx-json-schema.html - - name: Upload - uses: actions/upload-artifact@v1 - with: - name: site-current - path: ./site - build_v2-draft: - name: Build v2-draft - if: github.ref == 'refs/heads/development/v2.3' - runs-on: ubuntu-latest - container: python:3 - steps: - - uses: actions/checkout@v2 - with: - ref: 'development/v2.3' - - name: Install pre-requisites - run: pip install -r requirements.txt - - name: Build - run: mkdocs build -v --clean - - name: Schema - run: generate-schema-doc schemas/spdx-schema.json site/spdx-json-schema.html - - name: Upload - uses: actions/upload-artifact@v1 - with: - name: site-v2-draft - path: ./site - publish: - name: Publish - runs-on: ubuntu-latest - needs: [build_current, build_v2-draft] - steps: - - name: Download current - uses: actions/download-artifact@v1 - with: - name: site-current - path: ./site - - name: Download v2-draft - uses: actions/download-artifact@v1 - with: - name: site-v2-draft - path: ./site/v2-draft - - name: Deploy - uses: peaceiris/actions-gh-pages@v3 - with: - DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }} - PUBLISH_BRANCH: gh-pages - PUBLISH_DIR: ./site diff --git a/.github/workflows/publish_common.yml b/.github/workflows/publish_common.yml deleted file mode 100644 index f28b24fb77..0000000000 --- a/.github/workflows/publish_common.yml +++ /dev/null @@ -1,35 +0,0 @@ -on: - repository_dispatch: - types: - - publish_spec - workflow_dispatch: - inputs: - ref: - description: Branch or tag to publish (e.g. refs/heads/development/v2). - required: true - default: refs/heads/master - aliases: - description: Space-delimited aliases to publish (e.g. latest v2-latest). - required: false -jobs: - build: - runs-on: ubuntu-latest - container: python:3 - steps: - - uses: actions/checkout@v3 - with: - ref: ${{ github.event.client_payload.ref || github.event.inputs.ref }} - fetch-depth: 0 # Because we will be pushing the gh-pages branch - token: ${{ secrets.ACTIONS_DEPLOY_KEY }} - - name: Install pre-requisites - run: pip install -r requirements.txt - - name: Install mike - run: pip install mike==1.2.0 - - name: Extract branch or tag name - id: extract-branch-or-tag-name - run: echo "::set-output name=ref_name::${REF##*/}" - with: - ref: ${{ github.event.client_payload.ref || github.event.inputs.ref }} - - name: Build docs - run: mike deploy ${{ steps.outputs.extract-branch-or-tag-name.name }} ${{ github.event.inputs.aliases }} - diff --git a/.github/workflows/publish_v3.yml b/.github/workflows/publish_v3.yml index 4315c9fb20..d7e50ac313 100644 --- a/.github/workflows/publish_v3.yml +++ b/.github/workflows/publish_v3.yml @@ -11,34 +11,36 @@ jobs: runs-on: ubuntu-latest container: python:3 env: + REF_SPEC: "development/v3.0.1" # spec branch/tag release + REF_MODEL: "main" # model branch/tag release + REF_PARSER: "main" # parser branch/tag release + GH_PAGES_BRANCH: "gh-pages" # branch name to publish HTML to + GIT_USER_NAME: "ci-bot" # for gh-pages commit + GIT_USER_EMAIL: "ci-bot@spdx.dev" # for gh-pages commit PARSER_OUTPUT_DIR: "__parser_output" # temp dir for output from spec-parser RDF_BASE_DIR: "" # change to "rdf" in new structure MKDOCS_BASE_DIR: "" # change to "mkdocs" in new structure MKDOCS_MODEL_YML: "mkdocs-files.yml" # contains list of model Markdown files BASE_MKDOCS_YML: "mkdocs.yml" # initial MkDocs configuration FULL_MKDOCS_YML: "__mkdocs-full.yml" # MkDocs configuration combined with model list - GIT_USER_NAME: "ci-bot" # for gh-pages commit - GIT_USER_EMAIL: "ci-bot@spdx.dev" # for gh-pages commit steps: - name: Checkout spdx-spec uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 with: - ref: development/v3.0.1 + ref: ${{ env.REF_SPEC }} path: spdx-spec fetch-depth: 0 # Because we will be pushing the gh-pages branch - name: Checkout spdx-3-model uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 with: repository: spdx/spdx-3-model - ref: main # for v3.0.1-draft, checkout latest from main (development) - # Once 3.0.1 released, use the following ref to checkout from the release tag - # ref: 3.0.1 # for v3.0.1 final release + ref: ${{ env.REF_MODEL }} path: spdx-3-model - name: Checkout spec-parser uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 with: repository: spdx/spec-parser - ref: main + ref: ${{ env.REF_PARSER }} path: spec-parser - name: Install pre-requisites for spdx-spec run: pip install -r spdx-spec/requirements.txt @@ -89,7 +91,7 @@ jobs: echo "---------------------" ls spdx-spec/docs/model echo "=====================" - - name: Generate JSON schema -- OLD DIR STRUCTURE + - name: Generate JSON schema # Will be redirected from https://spdx.org/schema/3.0.0/spdx-json-schema.json # and available at https://spdx.github.io/spdx-spec/v3.0/model/schema.json run: | @@ -108,9 +110,9 @@ jobs: - name: Set Git identity working-directory: spdx-spec run: git config user.name $GIT_USER_NAME; git config user.email $GIT_USER_EMAIL - - name: Sync gh-pages + - name: Sync GitHub Pages working-directory: spdx-spec - run: git checkout gh-pages && git pull && git checkout development/v3.0.1 + run: git checkout $GH_PAGES_BRANCH && git pull && git checkout $REF_SPEC - name: Build complete MkDocs configuration working-directory: spdx-spec run: | From a1bf5b0c3d70a4d9bfbd048f7d3a603c7c896ef8 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Mon, 2 Sep 2024 16:54:01 +0100 Subject: [PATCH 03/12] Copy JSON annotations, JSON schema, JSON-LD context, and RDFs to alias directories Signed-off-by: Arthit Suriyawongkul --- .github/workflows/publish_v3.yml | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/.github/workflows/publish_v3.yml b/.github/workflows/publish_v3.yml index d7e50ac313..ab819a9ca1 100644 --- a/.github/workflows/publish_v3.yml +++ b/.github/workflows/publish_v3.yml @@ -15,11 +15,12 @@ jobs: REF_MODEL: "main" # model branch/tag release REF_PARSER: "main" # parser branch/tag release GH_PAGES_BRANCH: "gh-pages" # branch name to publish HTML to + VERSION_ALIASES: "latest v3.0 v3.0.1-draft v3-draft v3.0-RC1 v3.0-RC2" # list of aliases for v3.0.1 GIT_USER_NAME: "ci-bot" # for gh-pages commit GIT_USER_EMAIL: "ci-bot@spdx.dev" # for gh-pages commit PARSER_OUTPUT_DIR: "__parser_output" # temp dir for output from spec-parser - RDF_BASE_DIR: "" # change to "rdf" in new structure - MKDOCS_BASE_DIR: "" # change to "mkdocs" in new structure + RDF_BASE_DIR: "" # change to "rdf" in new spec-parser output dir structure + MKDOCS_BASE_DIR: "" # change to "mkdocs" in new spec-parser output dir structure MKDOCS_MODEL_YML: "mkdocs-files.yml" # contains list of model Markdown files BASE_MKDOCS_YML: "mkdocs.yml" # initial MkDocs configuration FULL_MKDOCS_YML: "__mkdocs-full.yml" # MkDocs configuration combined with model list @@ -129,12 +130,13 @@ jobs: echo "---------------------" cat "$FULL_MKDOCS_YML" echo "[End of File]" + rm $MKDOCS_MODEL_YML - name: Deploy and set aliases working-directory: spdx-spec run: | mike delete --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push --allow-empty v3.0 || true mike delete --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push --allow-empty v3.0.1-draft || true - mike deploy --update-aliase --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push v3.0.1 v3.0.1-draft v3-draft v3.0-RC1 v3.0-RC2 v3.0 latest + mike deploy --update-aliase --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push v3.0.1 $VERSION_ALIASES mike set-default --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push v3.0.1 # Explanations of the above mike steps: # 1) delete existing v3.0 alias/deployment, if exists @@ -143,3 +145,14 @@ jobs: # 4) set default version to v3.0.1 # A script for additional redirections will be run after this point # See https://github.com/spdx/spdx-spec/issues/1069 + - name: Copy JSON annotations, JSON schema, JSON-LD context, and RDFs to alias directories + # Fallback for backward compatibility with old URLs before v3.0.1 + working-directory: spdx-spec + run: | + git checkout $GH_PAGES_BRANCH + dirs="$VERSION_ALIASES" + for dir in $dirs; do + mkdir -p "$dir"/rdf + cp v3.0.1/rdf/* "$dir"/rdf + cp v3.0.1/rdf/* "$dir"/model + done From c6324a44217ec68bdead5d3b9138e576f292f5d8 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Mon, 2 Sep 2024 17:21:17 +0100 Subject: [PATCH 04/12] Commit RDF files in aliases Signed-off-by: Arthit Suriyawongkul --- .github/workflows/publish_v3.yml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/workflows/publish_v3.yml b/.github/workflows/publish_v3.yml index ab819a9ca1..00c7790abc 100644 --- a/.github/workflows/publish_v3.yml +++ b/.github/workflows/publish_v3.yml @@ -130,7 +130,6 @@ jobs: echo "---------------------" cat "$FULL_MKDOCS_YML" echo "[End of File]" - rm $MKDOCS_MODEL_YML - name: Deploy and set aliases working-directory: spdx-spec run: | @@ -143,8 +142,6 @@ jobs: # 2) delete existing v3.0.1-draft alias/deployment, if exists # 3) deploy v3.0.1, with aliases (v3.0.1-draft, v3-draft, v3.0-RC1, v3.0-RC2, v3.0 latest) # 4) set default version to v3.0.1 - # A script for additional redirections will be run after this point - # See https://github.com/spdx/spdx-spec/issues/1069 - name: Copy JSON annotations, JSON schema, JSON-LD context, and RDFs to alias directories # Fallback for backward compatibility with old URLs before v3.0.1 working-directory: spdx-spec @@ -155,4 +152,9 @@ jobs: mkdir -p "$dir"/rdf cp v3.0.1/rdf/* "$dir"/rdf cp v3.0.1/rdf/* "$dir"/model + git add "$dir"/rdf/* "$dir"/model/* done + git commit -m "Copy schema and RDFs to alias directories: $VERSION_ALIASES" + git push origin $GH_PAGES_BRANCH + # A script for additional redirections for properties with new name will be run after this point + # See https://github.com/spdx/spdx-spec/issues/1069 From 893aa2e6db12874118fdb799b0685efd917c3e23 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Tue, 3 Sep 2024 02:37:51 +0100 Subject: [PATCH 05/12] Add model redirections Signed-off-by: Arthit Suriyawongkul --- .github/workflows/publish_v3.yml | 97 ++++++++++++++++++++++++-------- etc/model-redirect-map.csv | 15 +++++ etc/model-redirect-template.html | 18 ++++++ 3 files changed, 105 insertions(+), 25 deletions(-) create mode 100644 etc/model-redirect-map.csv create mode 100644 etc/model-redirect-template.html diff --git a/.github/workflows/publish_v3.yml b/.github/workflows/publish_v3.yml index 00c7790abc..9e43a29764 100644 --- a/.github/workflows/publish_v3.yml +++ b/.github/workflows/publish_v3.yml @@ -15,6 +15,7 @@ jobs: REF_MODEL: "main" # model branch/tag release REF_PARSER: "main" # parser branch/tag release GH_PAGES_BRANCH: "gh-pages" # branch name to publish HTML to + VERSION: "v3.0.1" # current version (default) VERSION_ALIASES: "latest v3.0 v3.0.1-draft v3-draft v3.0-RC1 v3.0-RC2" # list of aliases for v3.0.1 GIT_USER_NAME: "ci-bot" # for gh-pages commit GIT_USER_EMAIL: "ci-bot@spdx.dev" # for gh-pages commit @@ -63,11 +64,11 @@ jobs: # Will be redirected from https://spdx.org/rdf/3.0.0/spdx-context.jsonld, spdx-model.ttl, etc. # and available at https://spdx.github.io/spdx-spec/v3.0/model/spdx-context.jsonld run: | - echo "=====================" + echo "====================" echo "Source: $PARSER_OUTPUT_DIR/$RDF_BASE_DIR" - echo "---------------------" + echo "--------------------" ls $PARSER_OUTPUT_DIR/$RDF_BASE_DIR - echo "=====================" + echo "====================" cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-context.jsonld spdx-spec/docs/rdf/ cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.dot spdx-spec/docs/rdf/ cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.json-ld spdx-spec/docs/rdf/ @@ -75,11 +76,11 @@ jobs: cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.ttl spdx-spec/docs/rdf/ cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.xml spdx-spec/docs/rdf/ cp spdx-spec/docs/rdf/spdx-model.json-ld spdx-spec/docs/rdf/spdx-model.jsonld - echo "=====================" + echo "====================" echo "Target (after copy): spdx-spec/docs/rdf" - echo "---------------------" + echo "--------------------" ls spdx-spec/docs/rdf - echo "=====================" + echo "====================" cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-context.jsonld spdx-spec/docs/model/ cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.dot spdx-spec/docs/model/ cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.json-ld spdx-spec/docs/model/ @@ -87,11 +88,11 @@ jobs: cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.ttl spdx-spec/docs/model/ cp $PARSER_OUTPUT_DIR/$RDF_BASE_DIR/spdx-model.xml spdx-spec/docs/model/ cp spdx-spec/docs/model/spdx-model.json-ld spdx-spec/docs/model/spdx-model.jsonld - echo "=====================" + echo "====================" echo "Target (after copy): spdx-spec/docs/model" - echo "---------------------" + echo "--------------------" ls spdx-spec/docs/model - echo "=====================" + echo "====================" - name: Generate JSON schema # Will be redirected from https://spdx.org/schema/3.0.0/spdx-json-schema.json # and available at https://spdx.github.io/spdx-spec/v3.0/model/schema.json @@ -125,23 +126,23 @@ jobs: d }" "$BASE_MKDOCS_YML" > "$FULL_MKDOCS_YML" sed -i "/__MODEL_PLACEHOLDER__/d" "$FULL_MKDOCS_YML" - echo "=====================" - echo "$FULL_MKDOCS_YML" - echo "---------------------" + echo "====================" + echo "Full MkDocs configuration: $FULL_MKDOCS_YML" + echo "--------------------" cat "$FULL_MKDOCS_YML" - echo "[End of File]" + echo "====================" - name: Deploy and set aliases working-directory: spdx-spec run: | - mike delete --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push --allow-empty v3.0 || true - mike delete --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push --allow-empty v3.0.1-draft || true - mike deploy --update-aliase --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push v3.0.1 $VERSION_ALIASES - mike set-default --config-file "$FULL_MKDOCS_YML" --branch gh-pages --push v3.0.1 + for alias in $VERSION_ALIASES; do + mike delete --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push --allow-empty "$alias" || true + done + mike deploy --update-aliase --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push $VERSION $VERSION_ALIASES + mike set-default --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push $VERSION # Explanations of the above mike steps: - # 1) delete existing v3.0 alias/deployment, if exists - # 2) delete existing v3.0.1-draft alias/deployment, if exists - # 3) deploy v3.0.1, with aliases (v3.0.1-draft, v3-draft, v3.0-RC1, v3.0-RC2, v3.0 latest) - # 4) set default version to v3.0.1 + # 1) delete existing aliases, if exists + # 2) deploy VERSION, with aliases (see VERSION_ALIASES) + # 3) set default version to VERSION - name: Copy JSON annotations, JSON schema, JSON-LD context, and RDFs to alias directories # Fallback for backward compatibility with old URLs before v3.0.1 working-directory: spdx-spec @@ -150,11 +151,57 @@ jobs: dirs="$VERSION_ALIASES" for dir in $dirs; do mkdir -p "$dir"/rdf - cp v3.0.1/rdf/* "$dir"/rdf - cp v3.0.1/rdf/* "$dir"/model + cp $VERSION/rdf/* "$dir"/rdf + cp $VERSION/rdf/* "$dir"/model git add "$dir"/rdf/* "$dir"/model/* done git commit -m "Copy schema and RDFs to alias directories: $VERSION_ALIASES" git push origin $GH_PAGES_BRANCH - # A script for additional redirections for properties with new name will be run after this point - # See https://github.com/spdx/spdx-spec/issues/1069 + - name: Make model redirections (for name changes) + # Fallback for backward compatibility with old URLs before v3.0.1 + # See name changes in https://github.com/spdx/spdx-3-model/blob/main/CHANGELOG.md + # More details at https://github.com/spdx/spdx-spec/issues/1069 + working-directory: spdx-spec + run: | + ALL_VERSIONS=$(echo "$VERSION" "$VERSION_ALIASES") + MAP_PATH="etc/model-redirect-map.csv" + TEMPLATE_PATH="etc/model-redirect-template.html" + INDEX_HTML="index.html" + git checkout $REF_SPEC + maps=$(cat "$MAP_PATH") + template=$(cat "$TEMPLATE_PATH") + echo "====================" + echo "Model redirection map: $MAP_PATH" + echo "--------------------" + echo "$maps" + echo "====================" + echo "====================" + echo "HTML redirection template: $TEMPLATE_PATH" + echo "--------------------" + echo "$template" + echo "====================" + git checkout $GH_PAGES_BRANCH + for alias in $ALL_VERSIONS; do + echo "$maps" | while read -r line; do + from=$(echo "$line" | cut -d',' -f1) + to=$(echo "$line" | cut -d',' -f2) + msg="Redirect: $alias/model/$from -> $VERSION/model/$to" + echo "$msg" + slash_count=$(echo "$from" | tr -cd '/' | wc -c) + upper_dirs="../.." + if [ -n "$from" ]; then + for i in $(seq 0 $slash_count); do + upper_dirs="$upper_dirs/.." + done + fi + escaped_upper=$(echo "$upper_dirs" | sed 's/[\/&]/\\&/g') + escaped_version=$(echo "$VERSION" | sed 's/[\/&]/\\&/g') + escaped_to=$(echo "$to" | sed 's/[\/&]/\\&/g') + html=$(echo "$template" | sed -e "s/__UPPER__/$escaped_upper/g" -e "s/__VERSION__/$escaped_version/g" -e "s/__TO__/$escaped_to/g") + mkdir -p "$alias/model/$from" + echo "$html" > "$alias/model/$from/$INDEX_HTML" + git add "$alias/model/$from/$INDEX_HTML" + done + done + git commit -m "Add model redirections for: $ALL_VERSIONS" + git push origin $GH_PAGES_BRANCH diff --git a/etc/model-redirect-map.csv b/etc/model-redirect-map.csv new file mode 100644 index 0000000000..cf7e8effeb --- /dev/null +++ b/etc/model-redirect-map.csv @@ -0,0 +1,15 @@ +,Core/Core +AI,AI/AI +Build,Build/Build +Core,Core/Core +Dataset,Dataset/Dataset +ExpandedLicensing,ExpandedLicensing/ExpandedLicensing +Extension,Extension/Extension +Licensing,Licensing/Licensing +Lite,Lite/Lite +Security,Security/Security +SimpleLicensing,SimpleLicensing/SimpleLicensing +Software,Software/Software +Core/Properties/imports,Core/Properties/import +Build/Properties/parameters,Build/Properties/parameter +Software/Properties/contentType,Core/Properties/contentType diff --git a/etc/model-redirect-template.html b/etc/model-redirect-template.html new file mode 100644 index 0000000000..90c8723b90 --- /dev/null +++ b/etc/model-redirect-template.html @@ -0,0 +1,18 @@ + + + + + Redirecting + + + + + Redirecting to __UPPER__/__VERSION__/model/__TO__/... + + From d1c53714dc862552633f4315ed1ab907b7c4a79a Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Tue, 3 Sep 2024 08:15:24 +0100 Subject: [PATCH 06/12] Note on plantuml Signed-off-by: Arthit Suriyawongkul --- .github/workflows/publish_v3.yml | 5 +++-- etc/model-redirect-map.csv | 11 +++++++++++ 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish_v3.yml b/.github/workflows/publish_v3.yml index 9e43a29764..80aad5ec12 100644 --- a/.github/workflows/publish_v3.yml +++ b/.github/workflows/publish_v3.yml @@ -62,7 +62,7 @@ jobs: cp spdx-spec/serialization/jsonld/annotations.ttl spdx-spec/docs/model/jsonld-annotations.ttl - name: Copy JSON-LD context and RDFs # Will be redirected from https://spdx.org/rdf/3.0.0/spdx-context.jsonld, spdx-model.ttl, etc. - # and available at https://spdx.github.io/spdx-spec/v3.0/model/spdx-context.jsonld + # and available at https://spdx.github.io/spdx-spec/v3.0/rdf/spdx-context.jsonld run: | echo "====================" echo "Source: $PARSER_OUTPUT_DIR/$RDF_BASE_DIR" @@ -95,7 +95,7 @@ jobs: echo "====================" - name: Generate JSON schema # Will be redirected from https://spdx.org/schema/3.0.0/spdx-json-schema.json - # and available at https://spdx.github.io/spdx-spec/v3.0/model/schema.json + # and available at https://spdx.github.io/spdx-spec/v3.0/rdf/schema.json run: | shacl2code generate \ --input spdx-spec/docs/rdf/spdx-model.ttl \ @@ -109,6 +109,7 @@ jobs: run: | cp -R $PARSER_OUTPUT_DIR/$MKDOCS_BASE_DIR/* spdx-spec/docs/model cp $PARSER_OUTPUT_DIR/$MKDOCS_MODEL_YML spdx-spec + # Do we need plantuml file here as well? - name: Set Git identity working-directory: spdx-spec run: git config user.name $GIT_USER_NAME; git config user.email $GIT_USER_EMAIL diff --git a/etc/model-redirect-map.csv b/etc/model-redirect-map.csv index cf7e8effeb..ef0de0fe29 100644 --- a/etc/model-redirect-map.csv +++ b/etc/model-redirect-map.csv @@ -10,6 +10,17 @@ Lite,Lite/Lite Security,Security/Security SimpleLicensing,SimpleLicensing/SimpleLicensing Software,Software/Software +ai,AI/AI +build,Build/Build +core,Core/Core +dataset,Dataset/Dataset +expandedlicensing,ExpandedLicensing/ExpandedLicensing +extension,Extension/Extension +licensing,Licensing/Licensing +lite,Lite/Lite +security,Security/Security +simplelicensing,SimpleLicensing/SimpleLicensing +software,Software/Software Core/Properties/imports,Core/Properties/import Build/Properties/parameters,Build/Properties/parameter Software/Properties/contentType,Core/Properties/contentType From 7ed905ea47d81f0e4b86f863e7665576a0bf0e67 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Tue, 3 Sep 2024 13:31:44 +0100 Subject: [PATCH 07/12] Support moved docs/annexes Signed-off-by: Arthit Suriyawongkul --- .github/workflows/publish_v3.yml | 52 ++++++++++++++++----------- etc/model-redirect-map.csv | 60 ++++++++++++++++++-------------- etc/model-redirect-template.html | 6 ++-- 3 files changed, 68 insertions(+), 50 deletions(-) diff --git a/.github/workflows/publish_v3.yml b/.github/workflows/publish_v3.yml index 80aad5ec12..d70453293e 100644 --- a/.github/workflows/publish_v3.yml +++ b/.github/workflows/publish_v3.yml @@ -160,8 +160,9 @@ jobs: git push origin $GH_PAGES_BRANCH - name: Make model redirections (for name changes) # Fallback for backward compatibility with old URLs before v3.0.1 - # See name changes in https://github.com/spdx/spdx-3-model/blob/main/CHANGELOG.md + # See name changes in model at https://github.com/spdx/spdx-3-model/blob/main/CHANGELOG.md # More details at https://github.com/spdx/spdx-spec/issues/1069 + # Add more redirections in etc/model-redirect-map.csv working-directory: spdx-spec run: | ALL_VERSIONS=$(echo "$VERSION" "$VERSION_ALIASES") @@ -184,25 +185,34 @@ jobs: git checkout $GH_PAGES_BRANCH for alias in $ALL_VERSIONS; do echo "$maps" | while read -r line; do - from=$(echo "$line" | cut -d',' -f1) - to=$(echo "$line" | cut -d',' -f2) - msg="Redirect: $alias/model/$from -> $VERSION/model/$to" - echo "$msg" - slash_count=$(echo "$from" | tr -cd '/' | wc -c) - upper_dirs="../.." - if [ -n "$from" ]; then - for i in $(seq 0 $slash_count); do - upper_dirs="$upper_dirs/.." - done - fi - escaped_upper=$(echo "$upper_dirs" | sed 's/[\/&]/\\&/g') - escaped_version=$(echo "$VERSION" | sed 's/[\/&]/\\&/g') - escaped_to=$(echo "$to" | sed 's/[\/&]/\\&/g') - html=$(echo "$template" | sed -e "s/__UPPER__/$escaped_upper/g" -e "s/__VERSION__/$escaped_version/g" -e "s/__TO__/$escaped_to/g") - mkdir -p "$alias/model/$from" - echo "$html" > "$alias/model/$from/$INDEX_HTML" - git add "$alias/model/$from/$INDEX_HTML" - done + from=$(echo "$line" | cut -d',' -f1) + to=$(echo "$line" | cut -d',' -f2) + slash_count=$(echo "$from" | tr -cd '/' | wc -c) + upper_dirs=".." + if [ -n "$from" ]; then + for i in $(seq 0 $slash_count); do + upper_dirs="$upper_dirs/.." + done + fi + escaped_upper=$(echo "$upper_dirs" | sed 's/[\/&]/\\&/g') + escaped_version=$(echo "$VERSION" | sed 's/[\/&]/\\&/g') + html="" + case "$to" in + http://*|https://*) + echo "Redirect: $alias/$from -> $to" + escaped_to=$(echo "$to" | sed 's/[\/&]/\\&/g') + html=$(echo "$template" | sed -e "s|__UPPER__/__VERSION__/__TO__|$escaped_to|g") + ;; + *) + echo "Redirect: $alias/$from -> $VERSION/$to" + escaped_to=$(echo "$to" | sed 's/[\/&]/\\&/g') + html=$(echo "$template" | sed -e "s/__UPPER__/$escaped_upper/g" -e "s/__VERSION__/$escaped_version/g" -e "s/__TO__/$escaped_to/g") + ;; + esac + mkdir -p "$alias/$from" + echo "$html" > "$alias/$from/$INDEX_HTML" + git add "$alias/$from/$INDEX_HTML" + done done - git commit -m "Add model redirections for: $ALL_VERSIONS" + git commit -m "Add redirections for: $ALL_VERSIONS" git push origin $GH_PAGES_BRANCH diff --git a/etc/model-redirect-map.csv b/etc/model-redirect-map.csv index ef0de0fe29..30a2c90695 100644 --- a/etc/model-redirect-map.csv +++ b/etc/model-redirect-map.csv @@ -1,26 +1,34 @@ -,Core/Core -AI,AI/AI -Build,Build/Build -Core,Core/Core -Dataset,Dataset/Dataset -ExpandedLicensing,ExpandedLicensing/ExpandedLicensing -Extension,Extension/Extension -Licensing,Licensing/Licensing -Lite,Lite/Lite -Security,Security/Security -SimpleLicensing,SimpleLicensing/SimpleLicensing -Software,Software/Software -ai,AI/AI -build,Build/Build -core,Core/Core -dataset,Dataset/Dataset -expandedlicensing,ExpandedLicensing/ExpandedLicensing -extension,Extension/Extension -licensing,Licensing/Licensing -lite,Lite/Lite -security,Security/Security -simplelicensing,SimpleLicensing/SimpleLicensing -software,Software/Software -Core/Properties/imports,Core/Properties/import -Build/Properties/parameters,Build/Properties/parameter -Software/Properties/contentType,Core/Properties/contentType +annexes/diffs-from-previous-editions,https://github.com/spdx/using/blob/main/docs/diffs-from-previous-editions.md +annexes/getting-started,https://github.com/spdx/using/blob/main/docs/getting-started.md +annexes/RDF-object-model-and-identifier-syntax,annexes/rdf-model +annexes/SPDX-license-expressions,annexes/spdx-license-expressions +annexes/using-SPDX-short-identifiers-in-source-files,https://github.com/spdx/using/blob/main/docs/using-SPDX-short-identifiers-in-source-files.md +annexes/using-SPDX-to-comply-with-industry-guidance,https://github.com/spdx/using/blob/main/docs/using-SPDX-to-comply-with-industry-guidance.md +annexes/including-security-information-in-SPDX,https://github.com/spdx/using/blob/main/docs/including-security-information-in-SPDX.md +annexes/SPDX-Lite,annexes/spdx-lite +model/,model/Core/Core +model/AI,model/AI/AI +model/Build,model/Build/Build +model/Core,model/Core/Core +model/Dataset,model/Dataset/Dataset +model/ExpandedLicensing,model/ExpandedLicensing/ExpandedLicensing +model/Extension,model/Extension/Extension +model/Licensing,model/Licensing/Licensing +model/Lite,model/Lite/Lite +model/Security,model/Security/Security +model/SimpleLicensing,model/SimpleLicensing/SimpleLicensing +model/Software,model/Software/Software +model/ai,model/AI/AI +model/build,model/Build/Build +model/core,model/Core/Core +model/dataset,model/Dataset/Dataset +model/expandedlicensing,model/ExpandedLicensing/ExpandedLicensing +model/extension,model/Extension/Extension +model/licensing,model/Licensing/Licensing +model/lite,model/Lite/Lite +model/security,model/Security/Security +model/simplelicensing,model/SimpleLicensing/SimpleLicensing +model/software,model/Software/Software +model/Core/Properties/imports,model/Core/Properties/import +model/Build/Properties/parameters,model/Build/Properties/parameter +model/Software/Properties/contentType,model/Core/Properties/contentType diff --git a/etc/model-redirect-template.html b/etc/model-redirect-template.html index 90c8723b90..b388f3f70e 100644 --- a/etc/model-redirect-template.html +++ b/etc/model-redirect-template.html @@ -4,15 +4,15 @@ Redirecting - Redirecting to __UPPER__/__VERSION__/model/__TO__/... + Redirecting to __UPPER__/__VERSION__/__TO__/... From 6330f6a6f4f68c848b3b965b3c47e79893985fc8 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Tue, 3 Sep 2024 14:13:51 +0100 Subject: [PATCH 08/12] Prepare to copy plantuml and jsondump Signed-off-by: Arthit Suriyawongkul --- .github/workflows/publish_v3.yml | 14 +++++++++----- etc/model-redirect-map.csv | 2 ++ setup.py | 2 +- 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/.github/workflows/publish_v3.yml b/.github/workflows/publish_v3.yml index d70453293e..47c8831464 100644 --- a/.github/workflows/publish_v3.yml +++ b/.github/workflows/publish_v3.yml @@ -15,8 +15,9 @@ jobs: REF_MODEL: "main" # model branch/tag release REF_PARSER: "main" # parser branch/tag release GH_PAGES_BRANCH: "gh-pages" # branch name to publish HTML to - VERSION: "v3.0.1" # current version (default) - VERSION_ALIASES: "latest v3.0 v3.0.1-draft v3-draft v3.0-RC1 v3.0-RC2" # list of aliases for v3.0.1 + VERSION: "v3.0.1" # publishing version + VERSION_DEFAULT: "v3.0.1" # default version (be redirected from https://spdx.github.io/spdx-spec/) + VERSION_ALIASES: "latest v3.0 v3.0.1-draft v3-draft v3.0-RC1 v3.0-RC2" # aliases for VERSION GIT_USER_NAME: "ci-bot" # for gh-pages commit GIT_USER_EMAIL: "ci-bot@spdx.dev" # for gh-pages commit PARSER_OUTPUT_DIR: "__parser_output" # temp dir for output from spec-parser @@ -109,7 +110,10 @@ jobs: run: | cp -R $PARSER_OUTPUT_DIR/$MKDOCS_BASE_DIR/* spdx-spec/docs/model cp $PARSER_OUTPUT_DIR/$MKDOCS_MODEL_YML spdx-spec - # Do we need plantuml file here as well? + # mkdir -p spdx-spec/docs/diagram + # cp $PARSER_OUTPUT_DIR/diagram/model.plantuml spdx-spec/docs/diagram + # mkdir -p spdx-spec/docs/jsondump + # cp $PARSER_OUTPUT_DIR/jsondump/model.json spdx-spec/docs/jsondump - name: Set Git identity working-directory: spdx-spec run: git config user.name $GIT_USER_NAME; git config user.email $GIT_USER_EMAIL @@ -139,11 +143,11 @@ jobs: mike delete --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push --allow-empty "$alias" || true done mike deploy --update-aliase --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push $VERSION $VERSION_ALIASES - mike set-default --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push $VERSION + mike set-default --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push $VERSION_DEFAULT # Explanations of the above mike steps: # 1) delete existing aliases, if exists # 2) deploy VERSION, with aliases (see VERSION_ALIASES) - # 3) set default version to VERSION + # 3) set default version to VERSION_DEFAULT - name: Copy JSON annotations, JSON schema, JSON-LD context, and RDFs to alias directories # Fallback for backward compatibility with old URLs before v3.0.1 working-directory: spdx-spec diff --git a/etc/model-redirect-map.csv b/etc/model-redirect-map.csv index 30a2c90695..fa86e76608 100644 --- a/etc/model-redirect-map.csv +++ b/etc/model-redirect-map.csv @@ -6,6 +6,8 @@ annexes/using-SPDX-short-identifiers-in-source-files,https://github.com/spdx/usi annexes/using-SPDX-to-comply-with-industry-guidance,https://github.com/spdx/using/blob/main/docs/using-SPDX-to-comply-with-industry-guidance.md annexes/including-security-information-in-SPDX,https://github.com/spdx/using/blob/main/docs/including-security-information-in-SPDX.md annexes/SPDX-Lite,annexes/spdx-lite +licenses/community-spec-1.0,licenses/Community-Spec-1.0 +licenses/cc-by-3.0,licenses/CC-BY-3.0 model/,model/Core/Core model/AI,model/AI/AI model/Build,model/Build/Build diff --git a/setup.py b/setup.py index ea7472adfc..4c7ae11e38 100644 --- a/setup.py +++ b/setup.py @@ -20,7 +20,7 @@ def read(fname): url = "https://spdx.org", long_description=read('README.md'), classifiers=[ - "Topic :: Dcoumentation", + "Topic :: Documentation", ], python_requires='>=2.7.9,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*', ) From 71bcb5096e11a47b54a52b02c2975052646febf6 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Tue, 3 Sep 2024 14:46:51 +0100 Subject: [PATCH 09/12] Add back index.md for home page (root) - Add back index.md since it is required as a home page, without it https://spdx.github.io/spdx-spec/v3.0.1/ will be 404 as there is no index.html generated - Rename docs/front/index.md to docs/front/copyright.md Signed-off-by: Arthit Suriyawongkul --- docs/front/copyright.md | 28 ++++++++++++++++++++++++++++ docs/{front => }/index.md | 28 ---------------------------- mkdocs.yml | 3 ++- submissions/ISO/README.md | 2 -- submissions/OMG/README.md | 2 -- submissions/OMG/front/cover.md | 2 -- submissions/OMG/front/second-page.md | 1 - 7 files changed, 30 insertions(+), 36 deletions(-) create mode 100644 docs/front/copyright.md rename docs/{front => }/index.md (66%) diff --git a/docs/front/copyright.md b/docs/front/copyright.md new file mode 100644 index 0000000000..8c108d7392 --- /dev/null +++ b/docs/front/copyright.md @@ -0,0 +1,28 @@ +# Use of Specification - Terms, Conditions & Notices + +Copyright © 2010-2024, The Linux Foundation and its Contributors, +including SPDX Model contributions from OMG and its Contributors. + +This work is licensed under the +[Community Specification License 1.0](../licenses/Community-Spec-1.0.md) +(Community-Spec-1.0). +Pre-existing portions of this work from copyright holders who have not +subsequently contributed under the Community-Spec-1.0 are provided under +[Creative Commons Attribution License 3.0 Unported](../licenses/CC-BY-3.0.md) +(CC-BY-3.0). +Copies of these licenses are reproduced in their entirety herein. + +## Trademarks + +SPDX® is a registered trademark of The Linux Foundation. + +## Compliance + +Use of the SPDX trademarks is subject to the SPDX Trademark License, +currently available at +[SPDX Legal Notices page](https://spdx.dev/about/legal-notices/). + +Software developed under the terms of the licenses under which this +specification is issued may claim compliance or conformance with this +specification if and only if the software provider complies with the +SPDX Trademark License given above. diff --git a/docs/front/index.md b/docs/index.md similarity index 66% rename from docs/front/index.md rename to docs/index.md index 485207f8d5..bde3e2d217 100644 --- a/docs/front/index.md +++ b/docs/index.md @@ -3,34 +3,6 @@ Copyright © 2010-2024, The Linux Foundation and its Contributors, including SPDX Model contributions from OMG and its Contributors. -## Use of Specification - Terms, Conditions & Notices - -This work is licensed under the -[Community Specification License 1.0](../licenses/Community-Spec-1.0.md) -(Community-Spec-1.0). -Pre-existing portions of this work from copyright holders who have not -subsequently contributed under the Community-Spec-1.0 are provided under -[Creative Commons Attribution License 3.0 Unported](../licenses/CC-BY-3.0.md) -(CC-BY-3.0). -Copies of these licenses are reproduced in their entirety herein. - -### Trademarks - -SPDX® is a registered trademark of The Linux Foundation. - -### Compliance - -Use of the SPDX trademarks is subject to the SPDX Trademark License, -currently available at -[SPDX Legal Notices page](https://spdx.dev/about/legal-notices/). - -Software developed under the terms of the licenses under which this -specification is issued may claim compliance or conformance with this -specification if and only if the software provider complies with the -SPDX Trademark License given above. - -## Thanks - With thanks to Adam Cohn, Adolfo García Veytia, diff --git a/mkdocs.yml b/mkdocs.yml index d34dc96360..5e5699b279 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,7 +35,8 @@ validation: absolute_links: warn unrecognized_links: warn nav: -- 'Copyright': front/index.md +- 'Home': index.md # index.md, which will be publish as index.html, is needed for a website as a default home +- 'Copyright': front/copyright.md - 'Introduction': front/introduction.md - '1. Scope': scope.md - '2. References': references.md diff --git a/submissions/ISO/README.md b/submissions/ISO/README.md index fad2742053..6224b02224 100644 --- a/submissions/ISO/README.md +++ b/submissions/ISO/README.md @@ -1,4 +1,3 @@ - Here are files that are only relevant to the production of the PDF that will be submitted to ISO. @@ -29,4 +28,3 @@ The structure of the PDF will include the following (in order): - licenses/Community-Spec-1.0 - licenses/CC-BY-3.0 - diff --git a/submissions/OMG/README.md b/submissions/OMG/README.md index 7d95419b7d..72b79156ed 100644 --- a/submissions/OMG/README.md +++ b/submissions/OMG/README.md @@ -1,4 +1,3 @@ - Here are files that are only relevant to the production of the PDF that will be submitted to OMG. @@ -32,4 +31,3 @@ The structure of the PDF will include the following (in order): - licenses/Community-Spec-1.0 - licenses/CC-BY-3.0 - diff --git a/submissions/OMG/front/cover.md b/submissions/OMG/front/cover.md index 3c4e2c6e97..d37daea25e 100644 --- a/submissions/OMG/front/cover.md +++ b/submissions/OMG/front/cover.md @@ -1,3 +1 @@ - # The System Package Data Exchange (SPDX) Specification Version 3.0.1 - diff --git a/submissions/OMG/front/second-page.md b/submissions/OMG/front/second-page.md index 4d99b09f6e..d89900c49a 100644 --- a/submissions/OMG/front/second-page.md +++ b/submissions/OMG/front/second-page.md @@ -28,4 +28,3 @@ Software developed under the terms of the licenses under which this specification is issued may claim compliance or conformance with this specification if and only if the software provider complies with the SPDX Trademark License given above. - From 6e1210d963bf4e34bc0ffbd71c5e201d0320ac81 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Wed, 4 Sep 2024 14:37:50 +0100 Subject: [PATCH 10/12] Add comments Signed-off-by: Arthit Suriyawongkul --- .github/workflows/publish_v3.yml | 35 ++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/.github/workflows/publish_v3.yml b/.github/workflows/publish_v3.yml index 47c8831464..d614c6c470 100644 --- a/.github/workflows/publish_v3.yml +++ b/.github/workflows/publish_v3.yml @@ -121,6 +121,12 @@ jobs: working-directory: spdx-spec run: git checkout $GH_PAGES_BRANCH && git pull && git checkout $REF_SPEC - name: Build complete MkDocs configuration + # Combines model file list (mkdocs-files.yml, generated by spec-parser) + # with the base mkdocs.yml file. + # The script below finds "__MODEL_PLACEHOLDER__" string in mkdocs.yml, + # replaces it with the content from mkdocs-files.yml, and writes the + # output to the full mkdocs.yml. + # The full mkdocs.yml will be used by mike in the deploy step. working-directory: spdx-spec run: | echo "Build $FULL_MKDOCS_YML from $BASE_MKDOCS_YML and $MKDOCS_MODEL_YML" @@ -137,6 +143,11 @@ jobs: cat "$FULL_MKDOCS_YML" echo "====================" - name: Deploy and set aliases + # mike is used here to manage multiple versions of MkDocs-powered documentation + # This step does 3 things: + # 1) delete existing aliases (in VERSION_ALIASES), if exists + # 2) deploy as VERSION, with aliases + # 3) set default version to VERSION_DEFAULT working-directory: spdx-spec run: | for alias in $VERSION_ALIASES; do @@ -144,12 +155,14 @@ jobs: done mike deploy --update-aliase --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push $VERSION $VERSION_ALIASES mike set-default --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push $VERSION_DEFAULT - # Explanations of the above mike steps: - # 1) delete existing aliases, if exists - # 2) deploy VERSION, with aliases (see VERSION_ALIASES) - # 3) set default version to VERSION_DEFAULT - name: Copy JSON annotations, JSON schema, JSON-LD context, and RDFs to alias directories # Fallback for backward compatibility with old URLs before v3.0.1 + # This step creates copies of annotations/schema/RDFs to all alias + # directories, so they can be accessible from all old URLs. + # For example, + # - https://spdx.github.io/spdx-spec/v3.0/model/schema.json + # - https://spdx.github.io/spdx-spec/v3.0.1/rdf/schema.json + # will all accessible and have the same content. working-directory: spdx-spec run: | git checkout $GH_PAGES_BRANCH @@ -162,11 +175,17 @@ jobs: done git commit -m "Copy schema and RDFs to alias directories: $VERSION_ALIASES" git push origin $GH_PAGES_BRANCH - - name: Make model redirections (for name changes) + - name: Make redirections (for model name changes and moved annexes) # Fallback for backward compatibility with old URLs before v3.0.1 + # More redirections can be added in etc/model-redirect-map.csv (from,to) # See name changes in model at https://github.com/spdx/spdx-3-model/blob/main/CHANGELOG.md - # More details at https://github.com/spdx/spdx-spec/issues/1069 - # Add more redirections in etc/model-redirect-map.csv + # This step creates a HTML files to facilitate additional directions. + # It reads a redirection map from etc/model-redirect-map.csv; + # in the CSV, first value is from (source) and second value is the to (target). + # The "from" and "to" values will be inserted into a HTML template at + # from etc/model-redirect-template.html, to create a redirection HTML + # page with a name of "from" that will refresh the browser with a URL + # of "to". working-directory: spdx-spec run: | ALL_VERSIONS=$(echo "$VERSION" "$VERSION_ALIASES") @@ -177,7 +196,7 @@ jobs: maps=$(cat "$MAP_PATH") template=$(cat "$TEMPLATE_PATH") echo "====================" - echo "Model redirection map: $MAP_PATH" + echo "Redirection map: $MAP_PATH" echo "--------------------" echo "$maps" echo "====================" From 0a339d38ece7830550dcd0cbc97e1db7f7bf285a Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Thu, 5 Sep 2024 09:05:47 +0100 Subject: [PATCH 11/12] Add more comments for make MkDocs config + Redirection - Add more comments and example to Redirection step - Move make MkDocs config script to bin + add more comments/usage - Revert newlines changes in submissions/ dir Signed-off-by: Arthit Suriyawongkul --- .github/workflows/publish_v3.yml | 89 +++++++++++-------- bin/make-mkdocs-config.sh | 59 ++++++++++++ ...odel-redirect-map.csv => redirect-map.csv} | 0 ...t-template.html => redirect-template.html} | 0 mkdocs.yml | 12 +-- submissions/ISO/README.md | 2 + submissions/OMG/README.md | 2 + submissions/OMG/front/cover.md | 2 + submissions/OMG/front/second-page.md | 1 + 9 files changed, 125 insertions(+), 42 deletions(-) create mode 100755 bin/make-mkdocs-config.sh rename etc/{model-redirect-map.csv => redirect-map.csv} (100%) rename etc/{model-redirect-template.html => redirect-template.html} (100%) diff --git a/.github/workflows/publish_v3.yml b/.github/workflows/publish_v3.yml index d614c6c470..63117eab0d 100644 --- a/.github/workflows/publish_v3.yml +++ b/.github/workflows/publish_v3.yml @@ -24,8 +24,10 @@ jobs: RDF_BASE_DIR: "" # change to "rdf" in new spec-parser output dir structure MKDOCS_BASE_DIR: "" # change to "mkdocs" in new spec-parser output dir structure MKDOCS_MODEL_YML: "mkdocs-files.yml" # contains list of model Markdown files - BASE_MKDOCS_YML: "mkdocs.yml" # initial MkDocs configuration - FULL_MKDOCS_YML: "__mkdocs-full.yml" # MkDocs configuration combined with model list + MKDOCS_BASE_YML: "mkdocs.yml" # initial MkDocs configuration + MKDOCS_FULL_YML: "__mkdocs-full.yml" # MkDocs configuration combined with model list + REDIRECT_MAP_PATH: "etc/redirect-map.csv" # redirect map + REDIRECT_TEMPLATE_PATH: "etc/redirect-template.html" # redirect HTML template steps: - name: Checkout spdx-spec uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7 @@ -121,26 +123,24 @@ jobs: working-directory: spdx-spec run: git checkout $GH_PAGES_BRANCH && git pull && git checkout $REF_SPEC - name: Build complete MkDocs configuration - # Combines model file list (mkdocs-files.yml, generated by spec-parser) - # with the base mkdocs.yml file. - # The script below finds "__MODEL_PLACEHOLDER__" string in mkdocs.yml, - # replaces it with the content from mkdocs-files.yml, and writes the - # output to the full mkdocs.yml. - # The full mkdocs.yml will be used by mike in the deploy step. + # Combines model file list (MKDOCS_MODEL_YML, generated by spec-parser) + # with the base MkDocs configuration file (MKDOCS_BASE_YML), + # to produce the full MkDocs configuration file (MKDOCS_FULL_YML). + # The script below finds "__MODEL_PLACEHOLDER__" string in + # MKDOCS_BASE_YML, replaces it with the content from MKDOCS_MODEL_YML. + # MKDOCS_FULL_YML will be used by mike in the deploy step. working-directory: spdx-spec run: | - echo "Build $FULL_MKDOCS_YML from $BASE_MKDOCS_YML and $MKDOCS_MODEL_YML" - sed -e "\|- model.*#.*__MODEL_PLACEHOLDER__.*|{ - r $MKDOCS_MODEL_YML - a\\ - - d - }" "$BASE_MKDOCS_YML" > "$FULL_MKDOCS_YML" - sed -i "/__MODEL_PLACEHOLDER__/d" "$FULL_MKDOCS_YML" + echo "Build $MKDOCS_FULL_YML from $MKDOCS_BASE_YML and $MKDOCS_MODEL_YML" + bin/make-mkdocs-config.sh \ + -b "$MKDOCS_BASE_YML" \ + -m "$MKDOCS_MODEL_YML" \ + -f "$MKDOCS_FULL_YML" \ + -p "__MODEL_PLACEHOLDER__" echo "====================" - echo "Full MkDocs configuration: $FULL_MKDOCS_YML" + echo "Full MkDocs configuration: $MKDOCS_FULL_YML" echo "--------------------" - cat "$FULL_MKDOCS_YML" + cat "$MKDOCS_FULL_YML" echo "====================" - name: Deploy and set aliases # mike is used here to manage multiple versions of MkDocs-powered documentation @@ -151,10 +151,10 @@ jobs: working-directory: spdx-spec run: | for alias in $VERSION_ALIASES; do - mike delete --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push --allow-empty "$alias" || true + mike delete --config-file "$MKDOCS_FULL_YML" --branch $GH_PAGES_BRANCH --push --allow-empty "$alias" || true done - mike deploy --update-aliase --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push $VERSION $VERSION_ALIASES - mike set-default --config-file "$FULL_MKDOCS_YML" --branch $GH_PAGES_BRANCH --push $VERSION_DEFAULT + mike deploy --update-aliase --config-file "$MKDOCS_FULL_YML" --branch $GH_PAGES_BRANCH --push $VERSION $VERSION_ALIASES + mike set-default --config-file "$MKDOCS_FULL_YML" --branch $GH_PAGES_BRANCH --push $VERSION_DEFAULT - name: Copy JSON annotations, JSON schema, JSON-LD context, and RDFs to alias directories # Fallback for backward compatibility with old URLs before v3.0.1 # This step creates copies of annotations/schema/RDFs to all alias @@ -175,33 +175,50 @@ jobs: done git commit -m "Copy schema and RDFs to alias directories: $VERSION_ALIASES" git push origin $GH_PAGES_BRANCH - - name: Make redirections (for model name changes and moved annexes) + - name: Make redirections (for renamed model elements and moved annexes) # Fallback for backward compatibility with old URLs before v3.0.1 - # More redirections can be added in etc/model-redirect-map.csv (from,to) - # See name changes in model at https://github.com/spdx/spdx-3-model/blob/main/CHANGELOG.md + # More redirections can be added in etc/redirect-map.csv (from,to) + # See name changes in model at + # https://github.com/spdx/spdx-3-model/blob/main/CHANGELOG.md + # # This step creates a HTML files to facilitate additional directions. - # It reads a redirection map from etc/model-redirect-map.csv; - # in the CSV, first value is from (source) and second value is the to (target). - # The "from" and "to" values will be inserted into a HTML template at - # from etc/model-redirect-template.html, to create a redirection HTML - # page with a name of "from" that will refresh the browser with a URL - # of "to". + # It reads a redirect map from etc/redirect-map.csv; in the CSV, + # first value is 'from' (source) and second value is 'to' (target). + # + # The 'from' and 'to' values will be inserted into a HTML template at + # from etc/redirect-template.html, to create a redirect HTML + # page (index.html) under a subdirectory with the name of 'from' + # that will refresh the browser to a URL of 'to'. + # + # For example, given + # VERSION = "v3.0.1" + # VERSION_ALIASES = "latest v3.0" + # from = "model/Core/Properties/imports" + # to = "model/Core/Properties/import" + # + # these HTML files will be created for every aliases: + # + # v3.0.1/model/Core/Properties/imports/index.html + # latest/model/Core/Properties/imports/index.html + # v3.0/model/Core/Properties/imports/index.html + # + # and all of them will redirect to + # + # v3.0.1/model/Core/Properties/import/ working-directory: spdx-spec run: | ALL_VERSIONS=$(echo "$VERSION" "$VERSION_ALIASES") - MAP_PATH="etc/model-redirect-map.csv" - TEMPLATE_PATH="etc/model-redirect-template.html" INDEX_HTML="index.html" git checkout $REF_SPEC - maps=$(cat "$MAP_PATH") - template=$(cat "$TEMPLATE_PATH") + maps=$(cat "$REDIRECT_MAP_PATH") + template=$(cat "$REDIRECT_TEMPLATE_PATH") echo "====================" - echo "Redirection map: $MAP_PATH" + echo "Redirect map: $REDIRECT_MAP_PATH" echo "--------------------" echo "$maps" echo "====================" echo "====================" - echo "HTML redirection template: $TEMPLATE_PATH" + echo "Redirect HTML template: $REDIRECT_TEMPLATE_PATH" echo "--------------------" echo "$template" echo "====================" diff --git a/bin/make-mkdocs-config.sh b/bin/make-mkdocs-config.sh new file mode 100755 index 0000000000..5747ac63b3 --- /dev/null +++ b/bin/make-mkdocs-config.sh @@ -0,0 +1,59 @@ +#! /bin/sh +# +# SPDX-License-Identifier: MIT +# +# Finds MODEL_PLACEHOLDER string in BASE_YML, +# replaces it with the content from MODEL_YML. + +usage() { + echo "Make MkDocs config" + echo "" + echo "Combines model file list (MODEL_YML)" + echo "with the base MkDocs configuration file (BASE_YML)," + echo "to produce the full MkDocs configuration file (FULL_YML)." + echo "" + echo "Usage: $0 -b -m -f [-p ]" + echo "" + echo "Inputs:" + echo " BASE_YML : a base MkDocs configuration file (usually, it is 'mkdocs.yml')." + echo " MODEL_YML : a model file list ('mkdocs-files.yml' from spec-parser)." + echo "" + echo "Output:" + echo " FULL_YML : a full MkDocs configuration, combining BASE_YML and MODEL_YML." + echo "" + echo "Option:" + echo " MODEL_PLACEHOLDER : a string inside BASE_YML that will be replaced by" + echo " a content from MODEL_YML. Default: '__MODEL_PLACEHOLDER__'" + echo "" + exit 1 +} + +while getopts "b:p:m:f:" opt; do + case $opt in + b) BASE_YML="$OPTARG" ;; + m) MODEL_YML="$OPTARG" ;; + f) FULL_YML="$OPTARG" ;; + p) MODEL_PLACEHOLDER="$OPTARG" ;; + *) usage ;; + esac +done + +# Set default value for MODEL_PLACEHOLDER if not provided +if [ -z "$MODEL_PLACEHOLDER" ]; then + MODEL_PLACEHOLDER="__MODEL_PLACEHOLDER__" +fi + +if [ -z "$BASE_YML" ] || [ -z "$MODEL_PLACEHOLDER" ] || [ -z "$MODEL_YML" ] || [ -z "$FULL_YML" ]; then + usage +fi + +sed -e "\|- model.*#.*$MODEL_PLACEHOLDER.*|{ + r $MODEL_YML + a\\ + + d +}" "$BASE_YML" > "$FULL_YML" + +TEMP_FILE=$(mktemp) +sed "/$MODEL_PLACEHOLDER/d" "$FULL_YML" > "$TEMP_FILE" +mv "$TEMP_FILE" "$FULL_YML" diff --git a/etc/model-redirect-map.csv b/etc/redirect-map.csv similarity index 100% rename from etc/model-redirect-map.csv rename to etc/redirect-map.csv diff --git a/etc/model-redirect-template.html b/etc/redirect-template.html similarity index 100% rename from etc/model-redirect-template.html rename to etc/redirect-template.html diff --git a/mkdocs.yml b/mkdocs.yml index 5e5699b279..bb5c24af8a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,10 +14,10 @@ plugins: - mike: canonical_version: v3.0.1 # tell search engines to prefer the URL of v3.0.1 alias_type: redirect # use redirect so it can redirect every pages (not just the root of the version) -- pdf-export: - combined: true - media_type: print - enabled_if_env: ENABLE_PDF_EXPORT # only export PDF if this is set to 1 +# - pdf-export: +# combined: true +# media_type: print +# enabled_if_env: ENABLE_PDF_EXPORT # only export PDF if this is set to 1 extra_css: - css/style.css markdown_extensions: @@ -44,8 +44,8 @@ nav: - '4. Terms and definitions': terms-and-definitions.md - '5. Conformance': conformance.md - '6. Model and serializations': serializations.md -- model: # __MODEL_PLACEHOLDER__, to be replaced by content from mkdocs-files.yml - - "__MODEL_PLACEHOLDER__": "https://example.com" # allows mkdocs.yml to be build/tested without full model list +- model: # __MODEL_PLACEHOLDER__, to be replaced by content from mkdocs-files.yml. Please do not edit this line. + - "__MODEL_PLACEHOLDER__": "https://example.com" # allows mkdocs.yml to be build/tested without full model list. Please do not edit this line. - annexes: - 'A. RDF model definition and diagrams': annexes/rdf-model.md - 'B. SPDX license expressions': annexes/spdx-license-expressions.md diff --git a/submissions/ISO/README.md b/submissions/ISO/README.md index 6224b02224..fad2742053 100644 --- a/submissions/ISO/README.md +++ b/submissions/ISO/README.md @@ -1,3 +1,4 @@ + Here are files that are only relevant to the production of the PDF that will be submitted to ISO. @@ -28,3 +29,4 @@ The structure of the PDF will include the following (in order): - licenses/Community-Spec-1.0 - licenses/CC-BY-3.0 + diff --git a/submissions/OMG/README.md b/submissions/OMG/README.md index 72b79156ed..7d95419b7d 100644 --- a/submissions/OMG/README.md +++ b/submissions/OMG/README.md @@ -1,3 +1,4 @@ + Here are files that are only relevant to the production of the PDF that will be submitted to OMG. @@ -31,3 +32,4 @@ The structure of the PDF will include the following (in order): - licenses/Community-Spec-1.0 - licenses/CC-BY-3.0 + diff --git a/submissions/OMG/front/cover.md b/submissions/OMG/front/cover.md index d37daea25e..3c4e2c6e97 100644 --- a/submissions/OMG/front/cover.md +++ b/submissions/OMG/front/cover.md @@ -1 +1,3 @@ + # The System Package Data Exchange (SPDX) Specification Version 3.0.1 + diff --git a/submissions/OMG/front/second-page.md b/submissions/OMG/front/second-page.md index d89900c49a..4d99b09f6e 100644 --- a/submissions/OMG/front/second-page.md +++ b/submissions/OMG/front/second-page.md @@ -28,3 +28,4 @@ Software developed under the terms of the licenses under which this specification is issued may claim compliance or conformance with this specification if and only if the software provider complies with the SPDX Trademark License given above. + From 085d39d5e38d1f964671de84d99c8e9c6d2e2038 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Thu, 5 Sep 2024 09:47:03 +0100 Subject: [PATCH 12/12] Add chapter redirections, due to v3.0.1 changes in name/dir structure - v3.0/introduction --> v3.0.1/front/introduction - v3.0/normative-references --> v3.0.1/references - v3.0/bibliography --> v3.0.1/references Signed-off-by: Arthit Suriyawongkul --- etc/redirect-map.csv | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/etc/redirect-map.csv b/etc/redirect-map.csv index fa86e76608..59b718c0c0 100644 --- a/etc/redirect-map.csv +++ b/etc/redirect-map.csv @@ -1,3 +1,6 @@ +introduction,front/introduction +normative-references,references +bibliography,references annexes/diffs-from-previous-editions,https://github.com/spdx/using/blob/main/docs/diffs-from-previous-editions.md annexes/getting-started,https://github.com/spdx/using/blob/main/docs/getting-started.md annexes/RDF-object-model-and-identifier-syntax,annexes/rdf-model @@ -8,7 +11,7 @@ annexes/including-security-information-in-SPDX,https://github.com/spdx/using/blo annexes/SPDX-Lite,annexes/spdx-lite licenses/community-spec-1.0,licenses/Community-Spec-1.0 licenses/cc-by-3.0,licenses/CC-BY-3.0 -model/,model/Core/Core +model,model/Core/Core model/AI,model/AI/AI model/Build,model/Build/Build model/Core,model/Core/Core