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]

@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 development/v3.0 branch, set checkout to use 3.0 tag
   • publish_v3.yml:

     - uses: actions/checkout@f4...44 # v3
     with:
       repository: spdx/spdx-3-model
       ref: 3.0
       path: spdx-3-model

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

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

3. on development/v3.0 branch, set canonical_version to latest
   • mkdocs.yml:

     - mike:
     canonical_version: 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 v3.0.1-draft -b gh-pages -p

   • 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/checkout@f4...44 # 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 v3.0.1 latest -b gh-pages -p

9. (once v3.0.1 is ready) on development/v3.0.1 branch, set canonical_version to latest
   • mkdocs.yml:

     - mike:
     canonical_version: latest

10. (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 #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)-(9) should be open and merge before (10)

--

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.