CFS API: Release Management

[FabrizioMoggio]

According to CAMARA WG: https://wiki.camaraproject.org/display/CAM/Release+Management+Working+Group

and specifically according to: https://wiki.camaraproject.org/display/CAM/API+versioning

In my understanding:

• we are in the Initial Phase: we currently have Rel 0.1.4-wip
• after the finalization of Conditional vs Unconditional forwarding #8, we can update the API according to the chosen option, and we can move to the Alpha phase, with Rel 0.2.0-alpha.1
• when we will start testing it we can go with Rel 0.x.y-beta.1 (update 04/06, now beta is called RC)

When we consolidate a release we think has a good value, we can create a branch for it (name: release-0.1.1-wip for example).
For each release branch, we need to add a Release Tag

[FabrizioMoggio]

Another interesting discussion on this topic: https://wiki.camaraproject.org/display/CAM/CAMARA+API+Maturity+Levels+-+proposal

[FabrizioMoggio]

when PR: #33 will be merged I propose to move forward with the versioning process moving from WIP to Alpha

[FabrizioMoggio]

To move to Alpha we should:

• name the release in the OAS file as: x.y.z-alpha.m. In this case: 0.1.7-alpha.1
• include the version in the URL: "{apiRoot}/call-forwarding-signal/vxalpham" . In this case: "{apiRoot}/call-forwarding-signal/v0alpha1"

[FabrizioMoggio]

About Release Tag: https://wiki.camaraproject.org/display/CAM/API+Release+Process#APIReleaseProcess-HowtocreateanAPIrelease?

We can address this when we have a consolidated Alpha version and a consistent Readiness Checklist.

[hdamker]

Just few remarks:

• The last digit in x.y.z indicates a patch version (e.g. a bug fix) of a previous released version x.y.0. As far as I can see, there was until now no release in this repository. But due to the assigned version numbers in previous commits it might make sense to have a clean start with v0.2.0-alpha.1 for the first pre-release.
• There is no need to assign a version number to unrelated API version. Within the new API versioning this explicit: every intermediate commit within main or another branch should have just "wip" as version. API YAMLs with "wip" can't be related
• A version number should be only set within a release PR (which is also changing the CHANGELOG.md accordingly). The merge commit of this PR will get then the release tag

[FabrizioMoggio]

@hdamker Thank you very much.

This is my understanding:

• Release in the OAS (x.y.z-alpha.m). In this case: 0.2.0-alpha.1
• we keep the URL version number as: "{apiRoot}/call-forwarding-signal/vwip"
• when we will have a consolidated Alpha, we will make a Release Tag and a specific Branch and we will include the release number in the URL.

[hdamker]

@FabrizioMoggio see inline:

This is my understanding:

• Release in the OAS (x.y.z-alpha.m). In this case: 0.2.0-alpha.1

Unless the OAS file is part of a release, the API version number should be also wip.

• we keep the URL version number as: "{apiRoot}/call-forwarding-signal/vwip"

Correct. Both the version field and the version within the URL are wip until you produce a release.

• when we will have a consolidated Alpha, we will make a Release Tag and a specific Branch and we will include the release number in the URL.

Yes - create a "release PR", which is only changing the version field, the version in URL and the CHANGELOG.md with the information about the release. Don't mix this PR with other changes of the OAS. After the PR is agreed create a GitHub release on the merge commit of this PR. A specific branch is not any more required, the release tag is defining the release.

BTW: release tags and the API versions within a release are now independent from each other. Example in your case: the first release tag could be r0.2 (to avoid to jump backwards in numbers), but it will continuing with r0.3 for the release with API version 0.2.0-rc.1, and r0.4 for a potential release candidate 0.2.0-rc.2. The public release would be in this example tagged r0.5 and contains the API version 0.2.0.

[FabrizioMoggio]

So, next steps:

• we work on a wip release till we have a stable version
• when we have a stable wip version, we create a PR only changing the version field, the version in URL and the CHANGELOG.md
• we create a Release Tag (no Branch is needed)

[FabrizioMoggio]

I propose to consider version: 0.1.8-wip as stable. To move forward to Alpha release.
Maybe before creating a Release Tag we still need to close some discussion.

[FabrizioMoggio]

Actually, according to: #27 (comment), we should proceed with Alpha and Release tag together.

[FabrizioMoggio]

Actually Release tagging for Alpha is not mandatory.

This is how release management works in my understanding:

• First development phase of a new release: WIP (no Release )
• New release consolidated, some improvement ongoing: Alpha (optional Pre-release or Alpha-release )
• Development completed, testing ongoing: -RC (Pre-release )

For Alpha, according to https://wiki.camaraproject.org/display/CAM/API+Release+Process: the Release Tag is not mandatory.

Anyway I propose to follow @hdamker suggestion and to move to Alpha in the YAML also creating a pre-release/alpha-release tag in the Repository.

This can be done after we close the ongoing discussion: #31 (comment)

[hdamker]

Some remarks:

• There is no need to change the version number between releases ... actually the YAML should only get a version number within a specific pull request to create the release commit which will be tagged as pre-release (alpha or rc) or public-release.
• Changes which are done between release pull request should set the version always to "wip" (no numbers in front)
• Patch version numbers are normally used only if you later need to patch a public-release, no need to use them in the release cycle. And patch versions must not contain breaking changes (0.1.7 to 0.1.8 in a9460c3 is a bad example - changing an enum into an array is a breaking change). But as said ... you would do this a "wip".
• Between alpha.n versions and towards rc.n versions.

Looking on your situation you have three options:

• Creating a pre-release r0.1 with 0.1.0-alpha.1 to communicate a first release which developers may use on own risk to test e.g. the implementation. As this might be confusing (as there were several v0.1.x versions in the history) my recommendation would be:
• Creating a pre-release r0.1 with API version 0.2.0-alpha.1 - your first tagged release, but version number set to the target number 0.2.0 -- release tag number and API version numbers are independent of each other).
• And you are right, you might decide to skip the pre-release with the alpha version. But it's recommended to wait with the rc version until when Commonalities and ICM has released their release candidate for the meta release. Then r0.1 would contain the API version v0.2.0-rc.1
• • The next change of the YAML will set the version field again to "wip" until you decide to do the next pre-release (tagged as r0.2), most probably with API version 0.2.0-rc.1 (or 0.2.0-rc.2)

Please feel free to involve the Release Management team (@camaraproject/release-management_maintainers) within your first release PR for support.

Please remind that release tags and API versions are decoupled!

[FabrizioMoggio]

@hdamker A wip version can not have any numbering. Did I got it right?

So it must be always: "version: wip".

If this is correct, to avoid confusion in with the different PRs, we can have an ad hoc numbering in the PR title to keep track. For example.

PR1: "Rel wip-1: added new feature blabla".
PR1: "Rel wip-2: changed blabla".

While the version filed in the YAMLs is always just: "version: wip"

Is my understanding correct?

Let me summarize my understanding of the different phases to see if I got them right:

The WIP phase is when you have a fast pace in the PRs with a planned work that, gradually introduces new features. The "version" filed is always set to "wip".

Then when we have a "very consolidated" YAML, when planned work is completed, we can move to Alpha with a Release Tag (pre-release). In this phase I don't expect planned improvements of the API, something can happen because of some discussion or issue, but it is an exception. And we use the numbering in the "version" filed to keep track.

When we start the testing against a real implementation, we can move to -RC.

Is this correct?

[tanjadegroot]

the wip is put in the yaml version field before the first pre-release and in between (pre-)releases to indicate that the API can be unstable due to multiple ongoing PRs. and should not be used.

There is no need to number the PRs with wip-1, wip-2 as you already have PR related issue numbers and the PR numbers using the GitHub change mgmt support. But if you want to do that, choice is up to the Sub Project.

Once the Sub Project team agrees that their YAML is consolidated, you can release an alpha API version.
This means (if your targeted API version to be released is 0.1.0):

• to put in the YAML Info object version field "0.1.0-alpha.1"
• to put in the YAML url field "v0.1alpha1" (exception case for v0.y.z API versions)
• to use the first release number "r1.1" (not "r0.1" - this was changed to further dissociate release numbering from API version numbering)

If more updates are needed you can create additional alpha releases.

For M3 you need to create the first release-candidate for testing.
Subsequent changes will imply to have additional release-candidate(s) until the final one by M4.

From the final release-candidate, the public-release PR shall be created.
This PR sets the version in the YAML to the targeted API version (0.1.0) and url (v0.1) - without any extension)

Hope this clarifies

[FabrizioMoggio]

Action: fix YAML removing release number from "version" field

Issue: #45