Publication source branches/tags and target URLs mapping/aliases

[bact]

This issue is for the discussion/documentation of the source branches/tags and the target URLs mapping for website/RDF publication, including default version/version aliases settings and appropriate version suffixes.

Background

With #1092 resolved, branches in spdx-spec repo got renamed like this:

• "master" -> "main"
• "development/v3.0.1" -> "develop"
• "development/v3.0" -> "support/3.0"

(spdx-3-model is not yet but will soon after 3.0.1 freeze)

Under new branch strategy:

• "main" is for the latest stable version, changes will be merged to this branch periodically (months) from a short-live administrative "release" branch (the "release" branch is created off the "develop")
• "develop" is for under development version, changes will be merged to this branch constantly (days)
• "support/3.0" is for the maintenance of version 3.0.x
• "hotfix" branches can be applied to "main" and "support" branches
• Translation is considered "support"
• See more in README at Branch Structure section

Publication CIs need to be adjusted, see PR #1146 for earlier discussion.

Notes

Note that currently the branch strategy is not entirely true yet:

• "main" should contain 3.0 (3.0.0), but currently is contains pre-3.0 development (the change log show "3.0 (TBD)")
• "support/3.0" contains 3.0, while in fact we can argue that the "support/3.0" should not exist yet at this time (since "develop" still contain 3.0.x development)

This is for historical/transitional reason and will eventually resolved soon after the release of 3.0.1.
It is very likely that at that point "support/3.0" will be post-3.0.1 maintenance, and "develop" will be 3.1 development.

Mapping proposal

I cannot really write it down to a general mapping rule yet, but below are some of the possible scenarios.

Hopefully we can use these for discussion, agreed on publication general mapping rule, and update #1146 with that general rule.

Note that will current mapping proposal, if we merge a "hotfix" to "main", the changes will not be get published unless we make another "release". Current proposal assume that all changes will go to either "develop" or "support" branch first.

To make things easier, we will neglect current facts stated in Notes above.

Scenario 1

• "main" is 3.0 release
• "develop" is 3.0.1 development
• "support/3.0" is not exist yet

Source branch/tag	Target URL
releases/tag/v3.0	https://spdx.github.io/spdx-spec/v3.0/
develop	https://spdx.github.io/spdx-spec/v3.0.1-dev/

Alias	Target version	Notes
(default)	v3.0	If no version given, redirect to the default version.
v3-draft	v3.0
v3.0-RC2	v3.0
v3.0.1	v3.0.1-dev

The "-dev" will be where spec and model developers can check the most recent changes, how HTML and RDF will look like.

Scenario 2

• "main" is 3.0.1 release
• "develop" is 3.1 development
• "support/3.0" is 3.0.x maintenance

Source branch/tag	Target URL	Notes
releases/tag/v3.0	https://spdx.github.io/spdx-spec/v3.0.0/	Republished in a new target URL
releases/tag/3.0.1	https://spdx.github.io/spdx-spec/v3.0.1/	New default
develop	https://spdx.github.io/spdx-spec/v3.1-dev/
support/3.0	https://spdx.github.io/spdx-spec/v3.0.2-dev/

Alias	Target version	Notes
(default)	v3.0.1	Updated
v3-draft	v3.0.1	Updated
v3.0-RC2	v3.0.1	Updated
v3.0	v3.0.1	New
v3.0.0	v3.0.0	New (do we still need this?)
v3.0.2	v3.0.2-dev	New
v3.1	v3.1-dev	New

Scenario 3

Same as Scenario 2 but now we have a release candidate for 3.1.

• "main" is 3.0.1 release
• "develop" is 3.1 development
• "support/3.0" is 3.0.x maintenance

Release candidate will be publish just like the stable release:

• While the version with "-RC" is from "develop" branch and considered under development, at the same time it is considered a "release", in a way that once released it should got fixated (as oppose to constantly changing as in the target URL with "-dev" suffix), so people can make reference to it reliably during the reviewing period.
  • See the existing RC: https://github.com/spdx/spdx-spec/releases/tag/v3.0-RC2
• This means we probably need a short-live "release" branch (similar to stable release) to publish to "-RC" target URL, because our "develop" publishes to "-dev" target URL.

Source branch/tag	Target URL	Notes
releases/tag/3.0.1	https://spdx.github.io/spdx-spec/v3.0.1/	Still default
releases/tag/3.1-RC1	https://spdx.github.io/spdx-spec/v3.1-RC1/
develop	https://spdx.github.io/spdx-spec/v3.1-dev/
support/3.0	https://spdx.github.io/spdx-spec/v3.0.2-dev/

Alias	Target version	Notes
(default)	v3.0.1
v3-draft	v3.0.1
v3.0-RC2	v3.0.1
v3.0	v3.0.1
v3.0.0	v3.0.0
v3.0.2	v3.0.2-dev
v3.1	v3.1-RC1	Updated

Scenario 4

• "main" is 3.1 release
• "develop" is 3.2 development
• "support/3.0" is 3.0.x maintenance
• "support/3.1" is 3.1.x maintenance

Source branch/tag	Target URL	Notes
releases/tag/3.0.1	https://spdx.github.io/spdx-spec/v3.0.1/
releases/tag/3.1	https://spdx.github.io/spdx-spec/v3.1/	New default
develop	https://spdx.github.io/spdx-spec/v3.2-dev/
support/3.0	https://spdx.github.io/spdx-spec/v3.0.2-dev/
support/3.1	https://spdx.github.io/spdx-spec/v3.1.1-dev/

Alias	Target version	Notes
(default)	v3.1	Updated
v3-draft	v3.1	Updated
v3.0-RC2	v3.0.1
v3.0	v3.0.1
v3.0.0	v3.0.0
v3.0.2	v3.0.2-dev
v3.1-RC1	v3.1	New
v3.1.1	v3.1.1-dev	New

Scenario 5

Same as Scenario 4 but now we have a new translation for 3.0.1.

• "main" is 3.1 release
• "develop" is 3.2 development
• "support/3.0" is 3.0.x maintenance
• "support/3.1" is 3.1.x maintenance

Source branch/tag	Target URL	Notes
releases/tag/3.0.1-ja	https://spdx.github.io/spdx-spec/v3.0.1/	Publish a support release (with new translation) to an existing target URL
releases/tag/3.1	https://spdx.github.io/spdx-spec/v3.1/	Still default
develop	https://spdx.github.io/spdx-spec/v3.2-dev/
support/3.0	https://spdx.github.io/spdx-spec/v3.0.2-dev/
support/3.1	https://spdx.github.io/spdx-spec/v3.1.1-dev/

Alias	Target version	Notes
(default)	v3.1
v3-draft	v3.1
v3.0-RC2	v3.0.1
v3.0	v3.0.1
v3.0.0	v3.0.0
v3.0.2	v3.0.2-dev
v3.1-RC1	v3.1
v3.1.1	*v3.1.1-dev

(Alias table remains unchanged from Scenario 4)

More questions about CI trigger

• At which point in time/what kind of event should we trigger the publication CI?
  • Under new branch structure, we will have an administrative "release" branch. Sould we trigger the publication CI from that "release" branch instead? I'm not entirely understand how "release" branch will be created.
• How are we going to publish the translation addition? Does what proposed in Scenario 5 make sense?