Update publish_v3.yml to alias "v3.0" (and later "v3.0.1") as "latest"

[bact]

.github/workflows/publish_v3.yml:

• Update alias argument for mike deploy to have v3.0 as the latest
  • v3.0 was aliased as v3-draft, so v2.3 still occupied the latest alias.

mkdocs.yml:

• mike section: Add canonical_version configuration as latest
  • This will help the latest appear near the first in search engine, among other versions, see https://github.com/jimporter/mike#configuration

Will fix #949

[goneall]

LGTM

[goneall]

@licquia - could you do a quick review

[goneall]

@bact @licquia - note the related PR #934 - can we combine these into one PR?

[bact]

@goneall @licquia Yes. If we don't plan to build docs for 3.0 again, I think it make sense to move over changes in this PR (publish_v3.yml and mkdocs.yml) to the PR #934, targeting 3.0.1.

[bact]

@goneall Updated. Bring in changes for 3.0.1 by @licquia from PR #934 to here.

[goneall]

Thanks @bact - @licquia and/or @zvr - if you could do a quick review, we can merge

[bact]

I'm not sure if we like to merge this at this time, since it has the tag latest and if the workflow starts it will publish the unfinished v3.0.1 - which I don't think we like it like that.

Normally, latest should point to the latest stable release, which is currently v3.0.

See more thoughts on this in next comment.

[bact]

I'm try to rethink and find what more logical is:

1. on every branches, set canonical_version to latest
   • mkdocs.yml:

     - mike:
       canonical_version: latest

2. on development/v3.0 branch, set checkout to use 3.0 tag of model
   • publish_v3.yml:

     - uses: actions/[email protected] # v3
       with:
         repository: spdx/spdx-3-model
         ref: 3.0
         path: spdx-3-model

3. on development/v3.0 branch, set latest alias to point to v3.0 version
   • publish_v3.yml:

     run: mike deploy -u -b gh-pages -p v3.0 latest

4. on development/v3.0 branch, run the publish workflow to have the proper latest on the current stable release (v3.0)
   • The reason that we may need to run the publish workflow of v3.0 again is to fix things like PRs 928, 943, 950, 958, 959 (clearly not a change in content; only web navigation structure or typos; so they are not v3.0.1)
5. on development/v3.0.1 branch, set the version (for mkdocs) to v3.0.1-draft (or v3.0.1-RCxxx) (an alias can be added, if needed)
   • publish_v3.yml:

     run: mike deploy -u -b gh-pages -p v3.0.1-draft

   • The CI will checkout from main branch (development branch)
   • The CI will publish the unfinished v3.01 to v3.0.1-draft version (selectable from dropdown list in HTML)
6. (once v3.0.1 is ready) on spdx-3-model repo, release it using the tag 3.0.1
7. (once v3.0.1 is ready) on development/v3.0.1 branch, set checkout to use 3.0.1 tag
   • publish_v3.yml:

     - uses: actions/[email protected] # v3
       with:
         repository: spdx/spdx-3-model
         ref: 3.0.1
         path: spdx-3-model

8. (once v3.0.1 is ready) on development/v3.0.1 branch, publish it with 3.0.1 version, with the alias latest
   • publish_v3.yml:

     run: mike deploy -u -b gh-pages -p v3.0.1 latest 

9. (once v3.0.1 is ready) on development/v3.0.1 branch, run the publish workflow to have the proper latest on the current stable release (now v3.0.1)

If this is correct and agreed:

• I should close this PR to and open a new pull request with content in (1)-(3) in development/v3.0 branch. That new PR will be reviewed and merged before (4).
• PR Update CI to build from and generate 3.0.1. #934 can be modified to be (5) and merge now, with the target of using it during the development period of v3.0.1
• Once v3.0.1 is ready, another PR with the content from (6)-(8) should be open and merge before (9)

--

Note: The content of (2)-(3) is PR #950 before the merge with #934 (this PR at the commit d44e0a6) but it should be on development/v3.0 branch instead.

[licquia]

With this change, we will be advertising 3.0.1 as the latest; if we want to change that, we can do that with a slight change and some manual runs of mike. But I think we should go forward with this at least as a first step.

[bact]

• Note: We also need to decide on how to update the copyright information at the footer of the page as well. Copyright information in mkdocs.yml need an update for v3. #930
  • It is in the copyright: section of mkdocs.yml

spdx-spec/mkdocs.yml

Line 2 in aac3e38

copyright: DRAFT version generated from d25ae89 (model) by 85e8d65 (parser)

[bact]

With this change, we will be advertising 3.0.1 as the latest; if we want to change that, we can do that with a slight change and some manual runs of mike. But I think we should go forward with this at least as a first step.

@licquia Also, this workflow need to be slightly adjusted once #978 and #979 are implemented - but I agree that we can take this PR as a first step and then having new PRs for new features.

[zvr]

No third-level number in URL

[zvr]

always use 3 levels

[bact]

Discussed in 2024-07-16 Tech team meeting - ready to merge.

[bact]

The deployment was failed because v2.3 still occupied "latest" alias. Need to use -u option in mike deploy to override that.

• To assign alias latest to v3.0, use this PR Republish 3.0 as 3.0.0 #994
• To publish v3.0.1 (development) as v3.0.1-draft, use this PR Publish 3.0.1 as v3.0.1-draft #995