version number on API Design Guidelines Doc [Commanalities]

[murthygorty]

Hi,
I think it will be useful to put a version number on the Design Guidelines doc, just like the APIs themselves.
This will allow us to iteratively improve on the Design Guidelines and the implementation itself may lag behind a little.

Thoughts?

[jordonezlucena]

Hi,

TEF standpoint is that it makes sense to implement versioning for guidelines.
However, what is important is to distinguish when a RFC means evolution, new considerations or breaking changes. For example, the outcome issue#157 resulted into a breaking change. With this distinction, if an approved RFC is breaking change, CAMARA APIs should be updated according this change, with this API update representing a major version.
According to this rationale, we propose to mark current guidelines with v1.0.0 and move forward as proposed above.

[murthygorty]

I agree - this is a sound idea.

[eric-murray]

@murthygorty
I agree adding an explicit version number to the design guidelines is a good idea, particularly when needing to refer to older versions of the guidelines. And I agree with the proposal from @jordonezlucena.

Can you confirm the intention is that the current "release" of the design guidelines will continue to be found in the main branch of the WorkingGroups repository, so there will be no "work in progress but unreleased" versions to be found there (unlike our OAS specifications)?

[murthygorty]

I didn't think of it when I raised the issue, but what you say makes sense @eric-murray. only 'released' design guidelines are in the main branch.
I'm wondering if it also makes sense to tag API spec with the version of the guideline it is following. It can be a nice-to-have. This will enable us in the future to have a 'dashboard/report on state of API'
cc: @shilpa-padgaonkar @gmuratk

[rartych]

In #173 (comment) @jordonezlucena proposed:

As for the WoW on versioning, TEF proposal is as follows:

• In API-design-guidelines.md, defining/enabling a versioning section that allows specifying the concrete version the guidelines doc referrs to.

• Creating a separate folder for each defined version, and uploading the corresponding doc there.

Finally, every API version (defined and maintained in the corresponding Sub-Project) should reference which version of the guidelines doc is built on.

In my opinion API Design Guidelines is still a 'living' document, with possible changes that should be implemented by subprojects - like it happened with camelCase parameter names or developer friendly naming. So changes are possible. It should be decided by Steering Committe when to freeze this document and call it version 1.0. - probably when some subprojects will be close to release 1.0. version of their APIs.

If keeping the track of the changes in any of guideline documents (API, AuthN&AuthZ, Release, ...) is needed to ease subprojects following the changes and to conform to guidelines then we can archive the snapshots of given guideline document:

• in WorkingGroups/Commonalities/documentation we can create /Archive folder
• when PR related to one of the guidelines document is discussed it should be decided (due to changes introduced but this PR) on making snapshot before merging this PR: then small, technical PR is created to add current version of the document with the name extended with date e.g.: API-design-guidelines-19_05_2023.md to /Archive folder
• additionally the file like API-design-guidelines-changelog.md can be created in the same folder to note changes introduced in given snapshot - introduction of Github PR template to WorkingGroups repository can help to collect this changes.

We can try this approach before merging PR #173 - on Event subscription/notification.

[jordonezlucena]

@rartych @bigludo7.
As for the versioning, we prefer to keep it with "API-design-guidelines-vx.y.z" format instead of "API-design-guidelines-vDD_MM_YYYY".
As for the change tracking, we agree on going for a separate changelog file.

[shilpa-padgaonkar]

The commonalities WG was created with an initial scope to create some best practice documents & discuss common issues that impact more than one Camara subproject. This scope over time has grown, and we have now reached a stage where we are creating artifacts such as CAMARA_common.json and others which will be referenced/reused by other subprojects.

One proposal would be to turn commonalities WG into a subproject of its own, where it will deliver these common artifacts (including documents) and have regular releases like other subprojects. This will allow other subprojects to refer to commonalities deliverables in a cleaner way.

Feedback/Alternatives for this proposal is appreciated.

[murthygorty]

Hi @shilpa-padgaonkar , that is an interesting notion. I don’t have a particularly strong preference

• one aspect to carefully consider is that commonalities is in fact different from other API family or service API — typical service API fits a mold like spec, documentation, etc, but commonalities may have more than one spec and different documentations, what do you think?
• one of your notions that we should definitely pursue is your commoner about converting commonalities into a for that has releases etc. this would bode well when we get to common version for all Camara (like the grand Camara 1.0 for example).

cc:@gmuratk

[shilpa-padgaonkar]

@murthygorty : Thank you for your feedback. Yes I agree that the commonalities subproject will not be able to follow the usual template of other subprojects but I don't see this as a showstopper.

[murthygorty]

sounds good @shilpa-padgaonkar. I too believe that this can be done, the artifacts from this subprojects vary, but incorporating as a subproject will make the upcoming 'release' also uniform.

[shilpa-padgaonkar]

#260

[shilpa-padgaonkar]

New repo created here https://github.com/camaraproject/Commonalities
Closing this issue.