Documentation ( Installation, Quick Start), Changelog template , Release process

[lalitb]

• Updated README.md with notes on Installation and Quick Start.
• Added Changelog.md template file.
• Added Release process. ( Similar to how it is done across other open-telemetry projects )

To summarize the release process as part of this PR:

1. CHANGELOG.md is managed manually, and as part of raising any PR, dev needs to add the summary of change under Unreleased section.
2. On day of release, Release manager decides on a tag say ( v0.0.1-beta).
3. He/She runs pre_release.sh which
   • creates a branch ( pre_release_v0.0.1-beta)
   • modifies CHANGELOG.md ( Search for ##Unreleased section and adds a new section with <tag> - <date> header beneath it. That way ##Unreleased section remains intact for new changes, and existing change-notes go within newly created section. I will reword the documentation.)
4. He/She creates a PR for these changelog.md changes, and waits for it to be merged to master.
5. Once PR is merged, he creates the above decided tag on the new merged commit hash.
6. He/She then goes to the github release UI page, and select "Create New Release". Specifies the tag created in step 5, and takes the curated contents as release notes, and creates the release.

[codecov]

Codecov Report

Merging #392 (92ac148) into master (9755c11) will increase coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #392      +/-   ##
==========================================
+ Coverage   94.72%   94.73%   +0.01%     
==========================================
  Files         175      175              
  Lines        7581     7581              
==========================================
+ Hits         7181     7182       +1     
+ Misses        400      399       -1     

Impacted Files	Coverage Δ
sdk/test/common/circular_buffer_test.cc	100.00% <0.00%> (+1.02%)	⬆️

[reyang]

LGTM with some minor formatting suggestions.

[maxgolov]

For managing release process - I'd suggest we use:

• GitHub UX for Release management - it covers creating tags in semver and creating release notes.
• for automated (nightly) - use the latest technology available: https://cli.github.com/ - that is gh release create: https://cli.github.com/manual/gh_release_create - which is great. It is gonna be harder for us to create something better than this in a limited time given.

Both options (GitHub Release tab and gh CLI) are industry standard. These are designed to be easy-to-use by any person, not necessarily dev. Plus, we'd have less of our own tooling to maintain.

[lalitb]

For managing release process - I'd suggest we use:

• GitHub UX for Release management - it covers creating tags in semver and creating release notes.
• for automated (nightly) - use the latest technology available: https://cli.github.com/ - that is gh release create: https://cli.github.com/manual/gh_release_create - which is great. It is gonna be harder for us to create something better than this in a limited time given.

Both options (GitHub Release tab and gh CLI) are industry standard. These are designed to be easy-to-use by any person, not necessarily dev. Plus, we'd have less of our own tooling to maintain.

The github UI is supposed to be used to publish a release as mentioned in final section of this document (https://github.com/open-telemetry/opentelemetry-cpp/blob/c0ea1fd587e1be0d99a97d639a1f82994515000c/RELEASING.md#release). I can make it explicit if this is not clear in document. The idea behind the first two steps are to manage the changelog.md. I am fine removing the second step ( Tagging ), and let the tag be created automatically by github UI if that's the ask ?

[maxgolov]

let the tag be created automatically by github UI if that's the ask ?

Yeah, we can assume that Release Manager can use their best judgement and UI (no scripts) to generate the next tag, given UI totally allows to do this without running any command-line tooling ( or gh utility can be used by those who prefer command line tooling ).

I think it's more valuable to do the following: generate version.h from git tag. So that when the build is built - we properly report the actual SDK version. We can probably re-generate version.h in git commit hook for incremental builds that includes commit id (or manage this in CI). But if we build from source based on tag - the version.h should reflect that tag information. That is the build tooling or CMake or bazel should re-generate the local version.h file (or mod it, if stored in source).. SDK must be able to know (and even in most cases, report) its version at runtime.

[lalitb]

let the tag be created automatically by github UI if that's the ask ?

Yeah, we can assume that Release Manager can use their best judgement and UI (no scripts) to generate the next tag, given UI totally allows to do this without running any command-line tooling ( or gh utility can be used by those who prefer command line tooling ).

I think it's more valuable to do the following: generate version.h from git tag. So that when the build is built - we properly report the actual SDK version. We can probably re-generate version.h in git commit hook for incremental builds that includes commit id (or manage this in CI). But if we build from source based on tag - the version.h should reflect that tag information. That is the build tooling or CMake or bazel should re-generate the local version.h file (or mod it, if stored in source).. SDK must be able to know (and even in most cases, report) its version at runtime.

OK Just saw this comment. My thoughts were to actually update the version.h along with CHANGELOG.md through pre_release.sh. Probably we can discuss this further in community meeting. I feel there are some gaps here.

[maxgolov]

Probably we can discuss this further in community meeting. I feel there are some gaps here.

We can describe the steps needed to create release / create tag with gh, and then publish the artifacts.... Maybe - as we publish the release using web-based UI, we can attach some form of a hook to automate the re-generation of the version header. Then even if Release Manager uses the release management tab / web-based UI to publish their notes, we can still properly patch the header with version that matches the git tag.

In another project we, first:

• manually update the version header.
• check it in (thru PR review process).
• maybe at this point of PR review we should also review the release notes.
• then once the updated header is checked in -- we use web-based UX to create the tag ( that must match what we specified earlier in the header ) + release notes under the release tab.

[alolita]

Some items to consider for releasing artifacts:

• Add guidelines on commit comments
• Automate changelog generation
• Determine what features consititute major, minor, patch builds in line with semver.org guidelines
• Add PR builds, nightly builds and release builds
• Is there a need to have a compatibility matrix (e.g. ABI version compatibility)
  Also to improve customer adoption:
• Make a sample app w the C++ library artifact in a Docker image available

[jsuereth]

under the assumption this is the start of the release process, looks great.

• I assume we'll be upadting the prepare_release script with more things we'd like. Specifically I'd like runtime visibility into the release version.
• I like Max's suggestion of gh utilities for doing release. The more automated the process can be the better. However, I'd always prefer HAVING a process over not, so let's not let perfect be the enemy of good.

[reyang]

There are still many open comments/discussion here, @lalitb please follow up in separate PRs. Thanks!

[lalitb]

Some items to consider for releasing artifacts:

• Add guidelines on commit comments
• Automate changelog generation
• Determine what features consititute major, minor, patch builds in line with semver.org guidelines
• Add PR builds, nightly builds and release builds
• Is there a need to have a compatibility matrix (e.g. ABI version compatibility)
  Also to improve customer adoption:
• Make a sample app w the C++ library artifact in a Docker image available

Really good points

• This is incremental process, and most of these points are planned.

[lalitb]

under the assumption this is the start of the release process, looks great.

• I assume we'll be upadting the prepare_release script with more things we'd like. Specifically I'd like runtime visibility into the release version.
• I like Max's suggestion of gh utilities for doing release. The more automated the process can be the better. However, I'd always prefer HAVING a process over not, so let's not let perfect be the enemy of good.

Runtime visibility of release version is planned, we have an open ticket for this.