Versioning of OAS yaml file in main branch between releases

[jlurien]

We have merged a couple of PRs into main without incrementing the version, which is still 0.8.0. And there are more on the queue. Anyone looking into the project from time to time may think that the current version in main is exactly the one we had one month ago. An also it is becoming more difficult to notice what changes.

I propose to give the file in main a new version, for example "0.9.0 DRAFT", so it is clear that is an evolution from 0.8.0. While a version is tagged as DRAFT we may add several changes without updating the version itself with each contribution, to be flexible. When we decide to release the 0.9.0 version we can remove the DRAFT suffix.

It would be useful as well to keep a changelog file next to the yaml file, to keep track of all changes in the fie, for example:

0.9.0 DRAFT

Added

• Error 500 added to all operations

  Changed

• Property notificationUri renamed to notificationUrl

  Fixed

• Couple of typos

We may have another changelog at root level as it is being discussed, documenting high level changes at project level between releases, but this other changelog is focused just on changes on the yaml file.

[eric-murray]

I agree that there is the potential for confusion here, and this probably should be part of the Versioning Guidelines discussion in Commonalities. As "version" is just a string field, my preference would be to set "version" to something like "NOT RELEASED" and only add the version number when it is included in a release.

The problem with nominating a specific version as the next release (e.g. 0.9.0 DRAFT) is that we can't be sure what the next release version will be. There were discussions on the next release being 0.8.1, rather than 0.9.0.

But it is a small point, and I agree with the general proposal

[sfnuser]

I agree with the proposal to update the version number to reflect changes. However, it would be nice to have the version number in some format to know the current baseline and also to use it in code/tools.

We could have the version as 0.8.0-<commit hash> - the hash being the merge commit of the last pull request but then the version update alone has to be done as a separate commit post merge. If this is an overkill, we could just have 0.8.0-vX and increment X for every PR merge.

[jlurien]

@SfnUser Problem with incrementing version with each PR is that when PR is proposed and being discussed, contributor does not know the relative merging order of this PR compared with other PRs discussed in parallel. Only when the PR is merged, we can know the order. One option is that code owner fix the version prior to each merge.

If we don't care about minor changes between releases we can keep the same version until next release. For that we can choose whatever name, something "version-neutral" as @eric-murray suggests, or give a candidate number to the release beyond current one, to make it clear that is incremental.

[hdamker]

Good discussion. I agree that it could be confusing and errorprone if the main branch still uses the version number of the past release. Nevertheless it is common practise within many open-source projects: in main is always the latests (un-released) code, if you need the released version look for the latest release branch. Within PR #99 for the new CHANGELOG.md I've copied the respective warning from draft versioning guidelines.

I looked a little bit around (e.g. here). None of the approaches seems to be perfect.

But I could live with bumping the number directly after creating a release branch to the next minor version and using an appendix like -pre or -wip. E.g. in our case v0.9.0-wip. We have then still the option to release a v0.8.1, just that we continue afterwards in main again with v0.9.0-wip.

For patches on release branches we just bump the patch number and add as well -wip. E.g. use v0.8.2-wip if we have to patch release-0.8.1 again after main has already larger changes.

[hdamker]

Regarding changelog: I'm strongly recommend to have only one CHANGELOG.md at the root of the project, reflecting all API objects within the repository/sub project, updated as part of every release. Everything else would be administrative overhead. If someone wants to see what changed in main since the last release there is always the commit history and the compare feature.

[sfnuser]

I agree with main having the latest updates and also the x.x.x-pre version format.

To summarize:

• Any fixes on a release (for e.g. v0.8.0) should be submitted on top of v0.8.0. Moderator would update the version and make a patch release v0.8.1. This commit (fix) will be cherry picked and updated in main later - I assume the PR owner should submit a separate PR on main if there are merge conflicts.

• If there is a PR, which is not backwards compatible, submitted on main (say v0.9.0-pre for the sake of discussion), if and when we decide to make a release on main, we shall release it as v1.0.0 and name the next main version as v1.1.0-pre. I am quoting this example to show v0.9.0-pre does not always mean there will be a v0.9.0 release and it could be bumped up based on the content. Do we agree on this understanding?

Overall, I am OK with the proposal @hdamker. Thanks.

[jlurien]

@hdamker Our particularity is that we are evolving a yaml file which is explicitly versioned. I'm fine with "0.9.0-wip" as a temporary version value for main.

Regarding changelog, my concern is that a changelog at root level deals with changes between releases at project level, which includes changes in the OAS API definition, but also other kind of changes like subproject reorgs, maintainance, etc. As API spec is the most important part of the project, I think it is important that the changelog documents in detail the changes between versions of the API spec, following the format proposed in the changelog template in Draft versioning guidelines doc. This is specially important once we reach a more stable version towards v1.0,0. We can build this level of detail incrementally with each PR or we can make the effort to summarize all changes once the next release is about to be created.

@SfnUser Regarding the second point about backward compatibility, I think we agreed on the last call that we will not take that considerations into account while we are still on v0.y.z. Once we reach a first v1.0.0 version we should take backward compatibility into account regarding major and minor versioning.

[sfnuser]

@jlurien Yes, you are correct. Post v1.0.0, we shall take backward compatibility into account.

[patrice-conil]

@SfnUser, @jlurien, @hdamker, @eric-murray, Another approach is to work on feature/release branches. Main is only used to reflect committed/running code and hold all version tags. Of course, the main branch is outdated but reflects the latest "everything is okay" code.

But as @hdamker said, neither approach seems perfect. My 2 cents. Patrice

[hdamker]

As discussed in call: release v0.8.1 done, version of qod-api.yaml bumped in main to 0.9.0-pre (to be used until we agree to create the next release after accumulated changes). Further discussions about version number in Commonalities.