add version and release best practices

[ajbalogh]

What: need to define a best practice for versioning and creating a release

Changing the version number in a file should not trigger the release process.
A non automated step is required to guard against releases getting created by accident.
The changes in this PR under best practices, versioning and creating a release are an attempt to formalize that process.

[ashutshkumr]

Let's bring this up in weekly sync-ups.

What's the problem with automatically creating releases upon version change in file ? I feel it is way less error-prone than manually creating git tags and pushing them (given that now we have multiple repositories which requires doing this).

Moreover, pushing generated code / file back to repository is not usually considered a best practice. I have seen such issues raised in multiple repositories - e.g. open-telemetry/opentelemetry-proto#77 (comment)

[ashutshkumr]

@ajbalogh can we revisit and finalize something on this ? I'm just noting down couple of frequent problem I hit everytime with this approach (when trying to create a new release):

• If I update version in api.yaml, commit it, tag it with newer version and push everything, pipeline fails (not sure why, need to investigate further).
• Otherwise I have to do two different pushes (one for api.yaml update and another for tag update).
• At times I tend to skip updating api.yaml and proceed forward with tag update, and it just creates a new release with openapi.yaml containing older version
• Lastly I can never create a release directly from browser, I always need to sync my workspace with latest and make modifications.

So seems like this method maybe more error-prone than previous method which just required updating version in api.yaml.

[ajbalogh]

Deprecated in favour of current do.py method of finding version in setup.py, checking for a tag