diff --git a/.github/workflows/publish_v3.yml b/.github/workflows/publish_v3.yml index 9505717dc8..4f0313f339 100644 --- a/.github/workflows/publish_v3.yml +++ b/.github/workflows/publish_v3.yml @@ -1,22 +1,41 @@ +# Publish SPDX specification to https://spdx.github.io/spdx-spec/ +# +# Overview: +# 1) Generate model documents and RDFs from model files in spdx-3-model repo +# 2) Combine the model documents from (1) with the chapters in spdx-spec repo +# 3) Generate a website using files from (2) +# 4) Upload RDFs from (1) and a website from (3) to GitHub Pages +# 5) Make URL redirections as needed +# +# See notes on running this workflow from "support" branch at: +# https://github.com/spdx/spdx-spec/pull/1146 + on: - # push: - # branches: - # - development/v3.0.1 - # repository_dispatch: - # types: - # - publish_v3_spec + push: + branches: + - main + repository_dispatch: + types: + - publish_v3_spec workflow_dispatch: {} # Manually trigger from https://github.com/spdx/spdx-spec/actions jobs: build: runs-on: ubuntu-latest env: - REF_SPEC: "development/v3.0.1" # spec branch/tag release + REF_SPEC: "main" # 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 - 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 + VERSION_DEFAULT: "v3.0.1" # default version; + # a version to be redirected from the URL without version number specified; + # VERSION_DEFAULT should be the same across all branches/tags + VERSION: "v3.0.1" # publishing version, to be publish by this workflow + # VERSION can be different from VERSION_DEFAULT; + # for example, if VERSION is a draft or a release candidate, + # or if VERSION is a stable version that is behind the default version (e.g. 3.0.2 vs 3.1) + VERSION_ALIASES: "latest 3.0.1 v3.0 v3.0.1-draft v3-draft v3.0-RC1 v3.0-RC2 3.0 3.0.1-draft 3-draft 3.0-RC1 3.0-RC2" + # VERSION_ALIASES are versions that will be redirected to VERSION; separated by space + # Note that the "latest" should be reserved for the latest version GIT_USER_NAME: "ci-bot" # for gh-pages commit GIT_USER_EMAIL: "ci-bot@spdx.dev" # for gh-pages commit PARSER_OUT_BASE_DIR: "__parser_out" # temp dir for output from spec-parser @@ -147,16 +166,24 @@ jobs: echo "====================" - name: Deploy and set aliases # mike is used here to manage multiple versions of MkDocs-powered documentation - # This step does 3 things: + # This step does 2 things: # 1) delete existing aliases (in VERSION_ALIASES), if exists # 2) deploy as VERSION, with aliases - # 3) set default version to VERSION_DEFAULT + # If the existing aliases were redirected to other versions, + # it means this VERSION will "steal" the aliases from those versions. working-directory: spdx-spec run: | for alias in $VERSION_ALIASES; do mike delete --config-file "$MKDOCS_FULL_YML" --branch $GH_PAGES_BRANCH --push --allow-empty "$alias" || true done mike deploy --update-aliase --config-file "$MKDOCS_FULL_YML" --branch $GH_PAGES_BRANCH --push $VERSION $VERSION_ALIASES + - name: Set default version + # Set default version to VERSION_DEFAULT; + # if not set, the default version will remain the same. + # Should only be done from the "main" branch. + if: github.ref == 'refs/heads/main' + working-directory: spdx-spec + run: | 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 @@ -195,7 +222,8 @@ jobs: # page (index.html) under a subdirectory with the name of 'from' # that will refresh the browser to a URL of 'to'. # - # For example, given + # For example, given: + # # VERSION = "v3.0.1" # VERSION_ALIASES = "latest v3.0" # from = "model/Core/Properties/imports"