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

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+### Added
+    * Trace API and SDK
+    * OTLP Exporter
+### Changed
+### Removed

INSTALL.md

@@ -0,0 +1 @@
+## TODO

README.md

@@ -20,11 +20,11 @@ Any exceptions to this are noted in the individual `README.md` files.
 
 ## Installation
 
-TBD
+Please refer to [INSTALL.md](./INSTALL.md).
 
-## Quick Start
-
-TBD
+## QuickStart
+The `examples/simple` directory contains a minimal program demonstrating
+how to instrument a small library using a simple `processor` and console `exporter`, along with build files for CMake and Bazel.
 
 ## Contributing
 

RELEASING.md

@@ -0,0 +1,39 @@
+# Release Process
+
+## Pre Release
+
+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>
+    ```
+3. Verify that CHANGELOG.md is updated properly:
+    ```
+    git diff master
+    ```
+4. Push the changes to upstream and create a Pull Request on GitHub.
+    Be sure to include the curated changes from the [Changelog](./CHANGELOG.md) in the description.
+
+## Tag
+
+Once the above Pull Request has been approved and merged it is time to tag the merged commit.
+
+***IMPORTANT***: It is critical you use the same tag that you used in the Pre-Release step!
+Failure to do so will leave things in a broken state.
+
+1. Note down the commit hash of the master branch after above PR request is merged : <commit-hash>
+    ```
+     git show -s --format=%H
+    ```
+2. Create a github tag on this commit hash:
+    ```
+    git tag -a "<new-tag>" -s -m "Version <new-tag>" "<commit-hash>"
+
+3. Push tag to upstream remote
+    ```
+    git push upstream
+    ```
+
+## 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.

pre_release.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+
+usage() { echo "Usage: $0 -t <tag>" 1>&2; exit 1; }
+
+while getopts ":t:" o; do
+    case "${o}" in
+        t)
+            tag=${OPTARG}
+            ;;
+        *)
+            usage
+            ;;
+    esac
+done
+if [ ! -z "${t}" ]; then
+    usage
+fi
+
+#validate tag
+semver_regex="^(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-]+)*)?$"
+if [[ ${tag} =~ ${semver_regex} ]]; then
+    echo "${tag} is valid semver tag"
+else
+    echo "Error: ${tag} is not a valid semver tag. Exiting"
+    exit -1
+fi
+
+#ensure tag doesn't exits
+if [[ $(git tag --list ${tag}) ]]; then
+   echo "Error: Tag ${tag} already exists. Exiting"
+   exit -1
+fi
+
+if ! git diff --quiet; then \
+	echo "Error: Working tree is not clean, can't proceed with the release process\n"
+	git status
+	git diff
+	exit 1
+fi
+
+# check changelog exists
+changelog_file="./CHANGELOG.md"
+if [ ! -f $changelog_file ]; then
+    echo "Error: $changelog_file doesn't exist. Ensure that you are running this script from repo root directory "
+    exit 1
+fi
+
+if [ ! grep -q "## [Unreleased]" $changelog_file ]; then
+    echo "Error: $changelog_file doesn't contain Unreleased information. Please update the file with changes and run this script again."
+    exit 1
+fi
+
+git checkout -b pre_release_${tag} master
+if [ $? -ne 0 ]; then
+    echo "Error: Cannot create release branch. Ensure you have sufficient permissions to repo and try again."
+    exit 1
+fi
+
+# update CHANGELOG.md
+date=$(date '+%Y-%m-%d')
+sed  -i "/\#\# \[Unreleased\]/a\\ \n\#\# \[${tag}\] ${date}"  $changelog_file
+if [$? -ne 0]; then
+    echo "Error: Cannot update CHANGELOG.md file. Update it manually, create the ${tag} and push changes to upstream"
+    exit 1
+fi
+
+git add .
+git commit -m "Prepare for releasing ${tag}"
+
+echo "Now validate the chages using git diff master, create the ${tag} and push changes to upstream"
+echo