Draft release guidelines doc #123

shilpa-padgaonkar · 2023-01-17T10:38:29Z

Fixes #118

added image for versioning-guideline doc

eric-murray · 2023-01-17T11:26:29Z

In the example, is the last release really meant to be release-0.2.0 rather than release-2.0.0? It is possible that release-0.2.0 could come after release-1.0.0 of course, but it is a confusing example as it implies that patch-1.0.1 and subsequent patches lead to release-0.2.0.

shilpa-padgaonkar · 2023-01-17T11:38:36Z

@eric-murray : The order is descending. On top you have latest=main, then 1.0.0 then 0.8.0, 02.0 and so on. So 0.2.0 is shown as the oldest release here. I will however change the patch direction (which probably was the reason for confusion)

jlurien · 2023-01-17T15:18:11Z

Commonalities/documentation/SupportingDocuments/Camara_Versioning_Guidelines.md

@@ -0,0 +1,20 @@
+# Camara versioning guidelines
+
+* Every release includes a **CHANGELOG.md** file. Please make sure that the content is structured in a format that is easy to read.


It would be good to agree on a common location for this file, for example code/API_definitions

@jlurien CHANGELOG.md is normally at the root of the repo alongside README.md

Yes, maybe instead of having a CHANGELOG.md for each realease is more convenient actually, to have a common file in main branch included all cumulative changes of each release/version i.e. actually each new release con just change that file adding the corresponding changes. Specific changes for each release could be included in the release notes, you could even include a link to the detailed change log using the compare github feature (you can compare your release against any previous tag/release).

@jpengar CHANGELOG.md will be made available in every release branch. It's location is right beside the README file. In the main branch the changelog file could either be kept empty or can be used to give an overview as you have stated above of the releases.

And we may think about using the github concept of pre-release if the release is not production ready.

jlurien · 2023-01-17T15:20:37Z

Commonalities/documentation/SupportingDocuments/Camara_Versioning_Guidelines.md

+# Camara versioning guidelines
+
+* Every release includes a **CHANGELOG.md** file. Please make sure that the content is structured in a format that is easy to read.
+* Release should follow the convention **\<subprj-name> \<tag-name>**


What is <subprj-name> here? Maybe providing an example would help

jlurien · 2023-01-17T15:37:53Z

Commonalities/documentation/SupportingDocuments/Camara_Versioning_Guidelines.md

+* Release should follow the convention **\<subprj-name> \<tag-name>**
+* Changelog content:
+    * APIs/Software in alpha release needs to be clearly specified
+    * API changes


We could propose a template, and give some guidelines about the expected level of detail, for example:

Changelog

X.Y.Z [ALPHA] - YYYY-MM-DD

Added

New property new_name

New endpoint new_name

Examples

Changed

Property old_name renamed to new_name

Format for property property changed to new_format

Fixed

Typos fixed

Reference corrected

Removed

Deprecated field old_field

Deprecated endpoint

@jlurien Much appreciated! I can add this as a separate md file and refer it in this doc

doc and link are now added

to address #123 (comment)

jpengar · 2023-01-17T15:51:56Z

Commonalities/documentation/SupportingDocuments/Camara_Versioning_Guidelines.md

+# Camara versioning guidelines
+
+* Every release includes a **CHANGELOG.md** file. Please make sure that the content is structured in a format that is easy to read.
+* Release should follow the convention **\<subprj-name> \<tag-name>** for e.g. qod v0.8.0


May be we could explicitly mention that we mean to use releases feature of github and link to the correpsonding documentation (https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository)

Good point. Done

jpengar · 2023-01-17T15:54:10Z

Commonalities/documentation/SupportingDocuments/Camara_Versioning_Guidelines.md

@@ -0,0 +1,20 @@
+# Camara versioning guidelines
+
+* Every release includes a **CHANGELOG.md** file. Please make sure that the content is structured in a format that is easy to read.


And we may think about using the github concept of pre-release if the release is not production ready.

Ref: #123 (comment)

added link to changelog template

to address #123 (comment)

formatting changes

formatting

updated to address camaraproject/QualityOnDemand#92 (comment)

formatting

hdamker · 2023-01-19T22:12:55Z

@jlurien

And we may think about using the github concept of pre-release if the release is not production ready.

I would reserve the "pre-release" feature of Github to release candidates (e.g. 0.9.0-rc) to mark releases as not yet final, e.g. that there could be minor corrections before the final release. My reasoning:

A release is on the complete subproject. It could contain APIs of different maturity grade side-by-side (e.g. an alpha and a beta version of the same API. Or a stable API and new one in alpha status). In the release notes and maybe also in the API definition file(s) the maturity has to be clearly stated.
A pre-release allows implementators a time to test the changes within the API definition before the release gets final (and would have then to be patched afterwards).
The pre-release feature is not suitable to indicate that the release is not production ready as it is only visible within Github, not in git. Therefore the "-rc" appendix to the release number as a proposal.

BTW: my "poster child" for a living versioning strategy in an open-source project is the Kubernetes Gateway API project: https://github.com/kubernetes-sigs/gateway-api/blob/main/CHANGELOG.md

shilpa-padgaonkar · 2023-01-20T13:34:20Z

After looking at some ongoing discussions in issue - camaraproject/QualityOnDemand#96 and this PR, I would like to add my 2-cents here :

In realistic scenario, we may have multiple API objects contained within a single API (bundle/family) for e.g. like in K8s
These API objects might be at different levels of maturity & might have different versions
An API object version number in general != API-bundle's release number (it could be so by coincidence)
When we make an API bundle release, then it can consist of one or more API objects with their specific versions.
API bundle releases are based on GIT Tags, which ensure that no objects can be changed in the release anymore.
If we have a semantic version in the API object's spec file, then this needs to be updated depending on the API change pull request (major, minor, patch).
If the subprojects do not wish to update the API object's version for every API change, they could simply specify the version not as semantic format but rather in custom formats such as v0alpha2, v1beta1 etc. (my preference)
Not every API-object(s) version change leads to a new release of an API bundle. API bundle releases are cherry-picked based on a consensus in the subproject.

jlurien · 2023-01-23T11:11:28Z

This is very relevant. As a WG/API "family" may include several API.yaml files and each one of these files may have a different version or stage of maturity, in general, a subproject relelease version does not have to always be the API version. Regarding changelogs, we may have a changelog per API just to document changes at API.yaml spec, and a changelog at root level to document changes between subproject releases. I know other people prefer to have a single changelog, but I think it is important to keep a track of changes per API spec as well. If we decide to have a single changelog per subproject, there should be a dedicated section documenting changes per API spec, in the format of the template. This is specially relevant once we reach maturity, from 1.0 specs, At some point we may need to publish the API specs somewehere out of github, and it will be convenient to have an explicit changelog per API spec, not relying on the commit history in Github.

shilpa-padgaonkar · 2023-01-24T14:23:03Z

@jlurien I surely agree that API changes should be part of changelog and this is already specified in the doc under section "Changelog content"

jlurien · 2023-01-24T14:51:44Z

@jlurien I surely agree that API changes should be part of changelog and this is already specified in the doc under section "Changelog content"

Yes, we all agree that "API changes" must be part of the release changelog. But I also think that the format of this section "API changes" within the release changelog should follow the format proposed in the changelog_template, detailing the changes within the API yaml. If an API familiy has several API yaml files, there should be a subsection within "API changes" per API with the changes in that API yaml. Not sure if all of us agree on the later. For v0.x versions is not that important.

shilpa-padgaonkar · 2023-01-24T15:15:28Z

@jlurien I have added an explicit note in the versioning doc. Feel free to update the template file with the format of your choice.

shilpa-padgaonkar · 2023-01-26T10:08:27Z

#137

jpengar · 2023-01-26T12:58:10Z

#137

It may be required to validate how this may affect or not to what was agreed in API Design Guidelines https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/API-design-guidelines.md#5-versioning.

Added note that commonalities will not impose restrictions regarding tags/branches not relevant for subproject releases

shilpa-padgaonkar · 2023-02-14T13:39:43Z

@jlurien @eric-murray @jpengar @jordonezlucena @FabrizioMoggio
Kindly request you to review the content. The current artefacts do not include any mention regarding change of api versioning from semantic to any other format. This currently just addresses the subproject release topic. This way we can try to get a consensus faster and then as a separate issue discuss the api versioning topic.
Hope this works for all.

jpengar · 2023-02-20T17:20:56Z

@jlurien @eric-murray @jpengar @jordonezlucena @FabrizioMoggio
Kindly request you to review the content. The current artefacts do not include any mention regarding change of api versioning from semantic to any other format. This currently just addresses the subproject release topic. This way we can try to get a consensus faster and then as a separate issue discuss the api versioning topic.
Hope this works for all.

LGTM.

It would be great though (at least for me ) to have a walk-through review (or similar) of the guidelines, just for everyone to know the recommended way of working for the CAMARA API/s subprojects. That way we could apply the same WoW in all subprojects. I mean WoW in terms of how to handle the branches and tags needed to create the releases according to the guidelines described here.

e.g. when to create the realease branch and tag; whether the realease branch should be developed in parallel to the main branch and only merge it into the main branch when that release is closed (so that the main branch has the latest stable release); or whether the main branch should always contain the latest status, even when a release is not closed, and then create the release branch from the main branch when the release is closed... If I've understood it properly you are proposing the second approach in this guidelines, but for example, so far I was using the first approach in HomeDevicesQoD subproject

shilpa-padgaonkar · 2023-02-24T10:42:20Z

@jpengar I will plan for a walkthrough in the next call as a part of the agenda

shilpa-padgaonkar added 2 commits January 17, 2023 11:27

Create Camara_Versioning_Guidelines.md

4fc9935

Add files via upload

76679bb

added image for versioning-guideline doc

shilpa-padgaonkar changed the title ~~Shilpa padgaonkar patch 2 1~~ Draft versioning guidelines doc Jan 17, 2023

formatting changes for versioning guidelines doc

1f39a9c

shilpa-padgaonkar requested review from jordonezlucena, eric-murray, jpengar and FabrizioMoggio January 17, 2023 10:41

shilpa-padgaonkar mentioned this pull request Jan 17, 2023

Proposal to release current HEAD of main as release v0.8.0 camaraproject/QualityOnDemand#92

Closed

Add files via upload

b352849

shilpa-padgaonkar added the commonalities label Jan 17, 2023

jlurien reviewed Jan 17, 2023

View reviewed changes

to address pr comment

92b2022

to address #123 (comment)

jpengar reviewed Jan 17, 2023

View reviewed changes

shilpa-padgaonkar added 7 commits January 17, 2023 16:58

Create CHANGELOG_TEMPLATE.md

77db1b7

Ref: #123 (comment)

Update Camara_Versioning_Guidelines.md

974fad5

added link to changelog template

Update Camara_Versioning_Guidelines.md

0442023

to address #123 (comment)

Update Camara_Versioning_Guidelines.md

4ce40f1

formatting changes

Update Camara_Versioning_Guidelines.md

85b9972

formatting

Update Camara_Versioning_Guidelines.md

e263637

Update Camara_Versioning_Guidelines.md

52afeb0

updated to address camaraproject/QualityOnDemand#92 (comment)

eric-murray previously approved these changes Jan 18, 2023

View reviewed changes

Update Camara_Versioning_Guidelines.md

43f89ad

shilpa-padgaonkar dismissed eric-murray’s stale review via 43f89ad January 18, 2023 16:59

shilpa-padgaonkar added 3 commits January 18, 2023 19:12

Update Camara_Versioning_Guidelines.md

4b88ad6

Add files via upload

0b98a97

Update Camara_Versioning_Guidelines.md

b2aa2a5

formatting

eric-murray mentioned this pull request Jan 19, 2023

Versioning of OAS yaml file in main branch between releases camaraproject/QualityOnDemand#96

Closed

hdamker mentioned this pull request Jan 19, 2023

Add CHANGELOG.md camaraproject/QualityOnDemand#98

Closed

shilpa-padgaonkar added 2 commits January 24, 2023 16:13

Update Camara_Versioning_Guidelines.md

bda8d3b

Update Camara_Versioning_Guidelines.md

b593882

hdamker mentioned this pull request Jan 25, 2023

Add-501-error-code-[NOT_IMPLEMENTED]-main (#4) camaraproject/QualityOnDemand#94

Closed

gmuratk mentioned this pull request Feb 3, 2023

Dealing with multiple API related artifacts of the same type and conformance to APIs #99

Closed

shilpa-padgaonkar changed the title ~~Draft versioning guidelines doc~~ Draft release guidelines doc Feb 14, 2023

shilpa-padgaonkar added 2 commits February 14, 2023 14:35

Update Camara_Versioning_Guidelines.md

396dfcf

Added note that commonalities will not impose restrictions regarding tags/branches not relevant for subproject releases

Update Camara_Versioning_Guidelines.md

b4474c8

shilpa-padgaonkar mentioned this pull request Feb 14, 2023

Recommendations for creating releases for various sub-projects #118

Closed

jordonezlucena removed their request for review February 21, 2023 16:20

eric-murray approved these changes Mar 8, 2023

View reviewed changes

shilpa-padgaonkar merged commit 843c23f into main Mar 15, 2023

shilpa-padgaonkar deleted the shilpa-padgaonkar-patch-2-1 branch March 15, 2023 10:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Draft release guidelines doc #123

Draft release guidelines doc #123

shilpa-padgaonkar commented Jan 17, 2023 •

edited

Loading

eric-murray commented Jan 17, 2023

shilpa-padgaonkar commented Jan 17, 2023 •

edited

Loading

jlurien Jan 17, 2023

shilpa-padgaonkar Jan 17, 2023

jpengar Jan 17, 2023 •

edited

Loading

shilpa-padgaonkar Jan 17, 2023

jpengar Jan 17, 2023

jlurien Jan 17, 2023 •

edited

Loading

shilpa-padgaonkar Jan 17, 2023

jlurien Jan 17, 2023

shilpa-padgaonkar Jan 17, 2023

shilpa-padgaonkar Jan 17, 2023

jpengar Jan 17, 2023

shilpa-padgaonkar Jan 17, 2023

jpengar Jan 17, 2023

hdamker commented Jan 19, 2023 •

edited

Loading

shilpa-padgaonkar commented Jan 20, 2023 •

edited

Loading

jlurien commented Jan 23, 2023

shilpa-padgaonkar commented Jan 24, 2023

jlurien commented Jan 24, 2023

shilpa-padgaonkar commented Jan 24, 2023

shilpa-padgaonkar commented Jan 26, 2023

jpengar commented Jan 26, 2023

shilpa-padgaonkar commented Feb 14, 2023

jpengar commented Feb 20, 2023 •

edited

Loading

shilpa-padgaonkar commented Feb 24, 2023

		@@ -0,0 +1,20 @@
		# Camara versioning guidelines

		* Every release includes a CHANGELOG.md file. Please make sure that the content is structured in a format that is easy to read.

Draft release guidelines doc #123

Draft release guidelines doc #123

Conversation

shilpa-padgaonkar commented Jan 17, 2023 • edited Loading

eric-murray commented Jan 17, 2023

shilpa-padgaonkar commented Jan 17, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jpengar Jan 17, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jlurien Jan 17, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Changelog

X.Y.Z [ALPHA] - YYYY-MM-DD

Added

Changed

Fixed

Removed

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hdamker commented Jan 19, 2023 • edited Loading

shilpa-padgaonkar commented Jan 20, 2023 • edited Loading

jlurien commented Jan 23, 2023

shilpa-padgaonkar commented Jan 24, 2023

jlurien commented Jan 24, 2023

shilpa-padgaonkar commented Jan 24, 2023

shilpa-padgaonkar commented Jan 26, 2023

jpengar commented Jan 26, 2023

shilpa-padgaonkar commented Feb 14, 2023

jpengar commented Feb 20, 2023 • edited Loading

shilpa-padgaonkar commented Feb 24, 2023

shilpa-padgaonkar commented Jan 17, 2023 •

edited

Loading

shilpa-padgaonkar commented Jan 17, 2023 •

edited

Loading

jpengar Jan 17, 2023 •

edited

Loading

jlurien Jan 17, 2023 •

edited

Loading

hdamker commented Jan 19, 2023 •

edited

Loading

shilpa-padgaonkar commented Jan 20, 2023 •

edited

Loading

jpengar commented Feb 20, 2023 •

edited

Loading