script to add versioning info (#399)

* version hook

* add version hook files

* format script

* add header in script

* update api version

* revert version.cc

* add updating ABI version

* add versioning guidelines

* move tag to new version

* fix relative link, update comment in version.cc

* Update RELEASING.md

Co-authored-by: Tom Tan <lilotom@gmail.com>

* another try on updating link

* added needed resources in docfx.json

Co-authored-by: Tom Tan <lilotom@gmail.com>

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Guideline to update the version:
+Increment the:
+- MAJOR version when you make incompatible API/ABI changes,
+- MINOR version when you add functionality in a backwards compatible manner, and
+- PATCH version when you make backwards compatible bug fixes.
+
+
 ## [Unreleased]
 ### Added
     * Trace API and SDK

RELEASING.md

@@ -5,8 +5,8 @@
 1. Make sure all relevant changes for this release are included under `Unreleased` section in `CHANGELOG.md` and are in language that non-contributors to the project can understand.
 
 2. Run the pre-release script. It creates a branch `pre_release_<new-tag>` and updates `CHANGELOG.md` with the `<new-tag>`:
-    ```
-    ./pre_release.sh -t <new-tag>
+    ```console
+    ./buildscripts/pre_release.sh -t <new-tag>
     ```
 3. Verify that CHANGELOG.md is updated properly:
     ```
@@ -35,5 +35,30 @@ Failure to do so will leave things in a broken state.
     git push upstream
     ```
 
+## Versioning:
+
+Once tag is created, it's time to use that tag for Runtime Versioning
+
+1. Create a new brach for updating version information in `./sdk/src/version.cc`.
+    ```
+        git checkout -b update_version_${tag} master
+    ```
+2. Run the pre-commit script to update the version:
+    ```console
+        ./buildscripts/pre-commit
+    ```
+
+3. Check if any changes made since last release broke ABI compatibility. If yes, update `OPENTELEMETRY_ABI_VERSION_NO` in [version.h](api/include/opentelemetry/version.h).
+
+4. Push the changes to upstream and create a Pull Request on GitHub.
+
+5. Once changes are merged, move the tag created earlier to the new commit hash from step 4.
+
+    ```
+    git tag -f <previous-tag> <new-commit-hash>
+    git push --tags --force
+
+    ```
+
 ## Release
 Finally create a Release for the new <new-tag> on GitHub. The release body should include all the release notes from the Changelog for this release.

buildscripts/pre-commit

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+
+# This script is supposed to be executed to recreate version.cc. It can be executed as:
+#    git pre-commit hook
+#    git per-merge-commit hook
+#    manually as part of release process ( refer RELEASING.md )
+
+set -eo pipefail
+
+if [[ ! -w "$(pwd)/sdk/src/version/version.cc"  && ! -w "$(pwd)/api/include/opentelemetry/version.h" ]]; then
+    echo "Error: Version file(s) are not writable. Check permissions and try again."
+    exit 1
+fi
+
+# format: "v<MAJOR>.<MINOR>.<PATCH>-<PRERELEASE>+<BUILDMETADATA>-<NUMBER_OF_NEW_COMMITS>-g<LAST_COMMIT_HASH>""
+semver_regex="^v(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(\\-([0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*))?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?-([0-9]+)-g([0-9|a-z]+)$"
+git_tag=$(git describe --tags --long 2>/dev/null) || true
+if [[ ! -z $git_tag ]] && [[ $git_tag =~ $semver_regex ]]; then
+    major="${BASH_REMATCH[1]}"
+    minor="${BASH_REMATCH[2]}"
+    patch="${BASH_REMATCH[3]}"
+    pre_release="${BASH_REMATCH[5]}" #optional
+    build_metadata="${BASH_REMATCH[7]}" #optional
+    count_new_commits="${BASH_REMATCH[9]}"
+    latest_commit_hash="${BASH_REMATCH[10]}"
+    if [[ -z ${major} ]] || [[ -z ${minor} ]] || [[ -z ${patch} ]] || [[ -z ${count_new_commits} ]] || [[ -z ${latest_commit_hash} ]]; then
+        echo "Error: Incorrect tag format recevived. Exiting.."
+        exit 1
+    fi
+else
+    major=0 && minor=0 && patch=0 && pre_release="" && build_metadata="" && count_new_commits=0
+    latest_commit_hash="$(git rev-parse --short HEAD)"
+fi
+: ${pre_release:="NONE"} # use default string if not defined
+: ${build_metadata:="NONE"} # use default string if not defined
+latest_commit_hash=$(git rev-parse ${latest_commit_hash}) # get full hash from short
+
+if [[ -z ${latest_commit_hash} ]]; then
+    echo "Error: Incorrect short hash received. Exiting.."
+    exit 1
+fi
+
+branch="$(git rev-parse --abbrev-ref HEAD)"
+short_version="${major}.${minor}.${patch}"
+full_version="${short_version}-${pre_release}-${build_metadata}-${count_new_commits}-${branch}-${latest_commit_hash}"
+
+#update api version.h
+sed -i "/^\#define OPENTELEMETRY_VERSION/c\#define OPENTELEMETRY_VERSION \"${short_version}\""  "$(pwd)/api/include/opentelemetry/version.h"
+#update sdk version.cc
+cat > "$(pwd)/sdk/src/version/version.cc" <<END
+// Please DONOT touch this file.
+// Any changes done here would be overwritten by pre-commit git hook
+
+#include "opentelemetry/sdk/version/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace version
+{
+    const int MAJOR_VERSION = ${major};
+    const int MINOR_VERSION = ${minor};
+    const int PATCH_VERSION = ${patch};
+    const char* PRE_RELEASE = "${pre_release}";
+    const char* BUILD_METADATA = "${build_metadata}";
+    const int COUNT_NEW_COMMITS = ${count_new_commits};
+    const char* BRANCH = "${branch}";
+    const char* COMMIT_HASH = "${latest_commit_hash}";
+    const char* SHORT_VERSION = "${short_version}";
+    const char* FULL_VERSION = "${full_version}";
+    const char* BUILD_DATE = "$(date -u)";
+}
+}
+OPENTELEMETRY_END_NAMESPACE
+END
+git add "$(pwd)/sdk/src/version/version.cc"

buildscripts/pre-merge-commit

@@ -0,0 +1 @@
+./pre-commit

ci/docfx.json

@@ -11,7 +11,10 @@
     "resource": [
       {
         "files": [
-
+          "api/**.h",
+          "api/**.cc",
+          "sdk/**.h",
+          "sdk/**.cc"
         ]
       }
     ],

sdk/include/opentelemetry/sdk/version/version.h

@@ -0,0 +1,23 @@
+#pragma once
+
+#include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace version
+{
+extern const int MAJOR_VERSION;
+extern const int MINOR_VERSION;
+extern const int PATCH_VERSION;
+extern const char *PRE_RELEASE;
+extern const char *BUILD_METADATA;
+extern const int COUNT_NEW_COMMITS;
+extern const char *BRANCH;
+extern const char *COMMIT_HASH;
+extern const char *FULL_VERSION;
+extern const char *FULL_VERSION_WITH_BRANCH_COMMITHASH;
+extern const char *BUILD_DATE;
+}  // namespace version
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE

sdk/src/CMakeLists.txt

@@ -2,3 +2,4 @@ add_subdirectory(common)
 add_subdirectory(trace)
 add_subdirectory(metrics)
 add_subdirectory(logs)
+add_subdirectory(version)

sdk/src/version/CMakeLists.txt

@@ -0,0 +1 @@
+add_library(opentelemetry_version version.cc)

sdk/src/version/version.cc

@@ -0,0 +1,24 @@
+// Please DONOT touch this file.
+// Any changes done here would be overwritten during release/build.
+
+#include "opentelemetry/sdk/version/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace version
+{
+const int MAJOR_VERSION     = 0;
+const int MINOR_VERSION     = 0;
+const int PATCH_VERSION     = 0;
+const char *PRE_RELEASE     = "";
+const char *BUILD_METADATA  = "";
+const int COUNT_NEW_COMMITS = 0;
+const char *BRANCH          = "";
+const char *COMMIT_HASH     = "";
+const char *SHORT_VERSION   = "";
+const char *FULL_VERSION    = "";
+const char *BUILD_DATE      = "";
+}  // namespace version
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE