Recommendations for creating releases for various sub-projects

[shilpa-padgaonkar]

No description provided.

[FabrizioMoggio]

Issue description:

An API Family is composed by more than one API. Each API, inside a Family, can be at different stage of development. How to manage different releases?

Example:

The EdgeCloud Family is composed by three APIs developed in the same Repo. Simple Edge Discovery, MEC exposure and experience management and Traffic Influence.

Issue: if one API has reached a stable point (a release), how can it be underlined in the Repo? How to continue to develop that API without loosing track of the release?

[FabrizioMoggio]

A possible solution could be based on branching and “Release” Tagging functionality natively available in GitHub (https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository). We suggest to create a release branch for each API inside an API Family. The people working on that API can make PRs on that branch to work on a release. The PR will be commented and, when agreed, the Family Owner will merge the PR in the Branch. When the development for that release is completed the Family Owner is notified and he creates a Release TAG on latest commit with the API project id name as a prefix (e.g. TI_v0.8.1). When ALL the APIs in a Family have reached a stable release and are Tagged with a Release, the Family Owner merges the branches into Main and creates a Release Tag for the merged API Family.

Example (EdgeCloud):

• 3 release branches are needed
• A commit related to a branch for Traffic Influence can have a “Release TAG” name TI_v0.8.1
• When all the 3 branches a have a “Release TAG”, Cristina (the Family Owner) can merge them into Main and can create a “Release TAG,” in Main, named v1.0.0

For the compete Family, the Developer searches for “Release Tags” into Main. For the release of a specific API, the Developer searches for “Release Tags” into the related Branch.

The three branches can be named like:

• Simple_Edge_Discovery
• MEC_exposure_and_ experience_management
  -Traffic_Influence

The Release Tags for the branches could be like:

• SED_v0.9.4
• MEC_v0.8.5
• TI_v0.8.1

For the Main Repo a prefix in the Tag is not requested. E.g. v1.0.0 is enough.

[FabrizioMoggio]

@shilpa-padgaonkar, the proposed diagram doesn't fit, in my understanding, the needs of an API Family where more that one API is included. The name of the Branches should be like API_1_name, API_2_name etc. Inside the Branch the "Release Tag" is used to identify v1.0.0, v2.0.0 etc. When the Branch API_1_name is tagged with a "Release Tag" it can be merged into the Main Branch. For example, for EdgeCloud we could have a branch named: Traffic_Influence. The first "Release Tag" would be v0.8.1. When an API Branch has a "Release Tag" it can be merged into Main. When ALL the API Branches are tagged and merged into Main we can make a "Release Tag" for Main an so for the Family

[shilpa-padgaonkar]

@FabrizioMoggio :

• The api.yaml spec file in the pic simply shows that there is a spec file provided for a certain endpoint from that API bundle. It does not give any details about its name. I can give it different names if that makes it clearer. But please note that these 2 endpoints belong to the same API bundle.

• Sorry, I am not sure if I get the point about tags inside branches. A tag simply points to a commit.

[FabrizioMoggio]

@shilpa-padgaonkar:

In my understanding the "endpoints" you were referencing are the different APIs from the API Family (or bundle). So one endpoint is the TI API, another endpoint the MEC Discovery API. If this is correct, we are aligned. We create a branch for each endpoint.

My comment on the on the "Release TAG" (https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) is exactly what you said. it is a pointer to a commit. That commit is intended to release a stable version of an API, released to developers to be used.

I see two possible approaches to track releases:

1. I create a new branch for each release and for each API. So I will have these branches: TI_API_V1, TI_API_V2, MEC_DISC_API_V1, MEC_DISC_API_V2 etc

2. (the one I was proposing with the tagging): I create just one branch for each API and inside the branch I underline the releases using the "Release TAG". So I just have these branches TI_API, MEC_DISC_API. Inside the branch TI_API I con find the different releases (commits) using the Github feature "Releases" that shows the "Release TAGs".

Which one do you prefer?

[shilpa-padgaonkar]

@FabrizioMoggio: In the last commonalities call it was agreed in the group that commonalities will not influence the way how a subproject would like to use branches and tags for their own specific needs. Commonalities will only provide guidelines for creating subproject releases (and hence focus only on release branch and release tag names).

The above mentioned branches and tags in your comment, I would not refer them as release branches or tags as release is at the repo level.

So your subproject is free to choose any naming convention or tags you prefer for the branches & tags which are not repo release related.

[FabrizioMoggio]

Conlusion: the "Camara subproject release guidelines" file defines how to manage the releases inside a subproject. The document also suggests to use the Release Tag feature from Github to mark the release. If a Subproject needs branches to work on different APIs (or for any other reason), this is up to the subproject to organize itself. Anyway the branches will be merged into the Main Repo where the Release Tag will be applied.

@shilpa-padgaonkar: is this understanding of mine correct?

[shilpa-padgaonkar]

@FabrizioMoggio: Yes, your understanding is correct.

[FabrizioMoggio]

The "Camara subproject release guidelines" file defines how to manage the releases inside a subproject.

[shilpa-padgaonkar]

@FabrizioMoggio : This issue would be closed when we are able to merge #123