Create RELEASE instructions (#101)

Renames bump_version.sh to pre_release.sh to match main otel repo.

Co-authored-by: Tyler Yahn <[email protected]>

RELEASING.md

@@ -0,0 +1,91 @@
+# Release Process
+
+There are two types of release for the `go.opentelemetry.io/contrib` repo
+and submodules.
+
+1. **Case 1** A release due to changes independent of the
+`go.opentelemetry.io/otel` module, e.g. perhaps a critical bug fix in
+one of the contrib modules.
+
+2. **Case 2** A release due to a breaking API change in
+`go.opentelemetry.io/otel` which all modules in this repo
+depend on.
+
+## Pre-Release
+
+Update go.mod for submodules to depend on the upcoming new release of
+the module in this repo, `go.opentelemetry.io/contrib`.  Decide on the
+next version of the semantic tag to apply to the contrib
+module based on whether you fall into Case 1 or Case 2.
+
+### Case 1
+
+If the changes are all internal to this repo, then the new tag will
+most often be a patch or minor version upgrade to the existing tag on
+this module. Let's call this `<new_contrib_tag>`.
+
+### Case 2
+
+If a new release is required due to breaking changes in
+`go.opentelemetry.io/otel`, then the new semantic tag for this repo
+should be bumped to match the `go.opentelemetry.io/otel` new tag.
+Let's call this `<new_otel_tag>`. The script checks that
+`go.opentelemetry.io/otel@v<new_otel_tag>` is a valid tag, so you need
+to wait until that tag has been pushed in the main repo.
+
+In nearly all cases, `<new_contrib_tag>` should be the same as
+`<new_otel_tag>`.
+
+1. Run `pre_release.sh` script to create a branch `pre_release_<new_contrib_tag>`.
+   The script will also run `go mod tidy` and `make ci`.
+
+   * **Case 1** `./pre_release.sh -t <new_contrib_tag>`
+   * **Case 2** `./pre_release.sh -o <new_otel_tag> [-t <new_contrib_tag>]`
+
+2. If you used `-o <new_otel_tag>` to rewrite the modules to depend on
+   a new version of `go.opentelemetry.io/otel`, there will likely be
+   breaking changes that require fixes to the files in this
+   `contrib` repo.  Make the appropriate fixes to address any API
+   breaks and run through the
+
+        ```
+        git commit -m "fixes due to API changes"
+        make precommit
+        ```
+
+   cycle until everything passes
+
+4. Push the changes to upstream.
+
+    ```
+    git diff master
+    git push
+    ```
+
+5. Create a PR on github and merge the PR once approved.
+
+
+### Tag
+Now create a `<new_contrib_tag>` on the commit hash of the changes made in pre-release step,
+
+1. Run the tag.sh script.
+2. Push tags upstream. Make sure you push upstream for all the sub-module tags as well.
+
+    ```
+    ./tag.sh -t <new_contrib_tag> -c <commit-hash>
+    git push upstream <new_contrib_tag>
+    git push upstream <submodules-path/new_contrib_tag>
+    ```
+
+## Release
+Now create a release for the new `<new_contrib_tag>` on github. tag.sh script generates commit logs since
+last release. Use that to draft the new release.
+
+<!-- ## Verify Examples -->
+<!-- After releasing run following script to verify that examples build outside of the otel repo. -->
+<!-- The script copies examples into a different directory and builds them. -->
+
+<!-- ``` -->
+<!-- ./verify_examples.sh -->
+<!-- ``` -->
+

bump_version.sh → pre_release.sh

@@ -23,18 +23,21 @@
 #
 set -e
 
+declare CONTRIB_TAG
+declare OTEL_TAG
+
 help() {
    printf "\n"
    printf "Usage: %s [-o otel_tag] [-t tag]\n" "$0"
    printf "\t-o Otel release tag. Update all go.mod to reference go.opentelemetry.io/otel <otel_tag>.\n"
-   printf "\t-t New unreleased tag. Update all go.mod with this tag.\n"
+   printf "\t-t New Contrib unreleased tag. Update all go.mod files with this tag.\n"
    exit 1 # Exit script after printing help
 }
 
 while getopts "t:o:" opt
 do
    case "$opt" in
-      t ) TAG="$OPTARG" ;;
+      t ) CONTRIB_TAG="$OPTARG" ;;
       o ) OTEL_TAG="$OPTARG" ;;
       ? ) help ;; # Print help
    esac
@@ -53,7 +56,7 @@ validate_tag() {
 }
 
 # Print help in case parameters are empty
-if [[ -z "$TAG" && -z "$OTEL_TAG" ]]
+if [[ -z "$CONTRIB_TAG" && -z "$OTEL_TAG" ]]
 then
     printf "At least one of '-o' or '-t' must be specified.\n"
     help
@@ -63,6 +66,7 @@ fi
 ## Validate tags first
 if [ -n "${OTEL_TAG}" ]; then
     validate_tag "${OTEL_TAG}" || exit $?
+
     # check that OTEL_TAG is a currently released tag for go.opentelemetry.io/otel
     TMPDIR=$(mktemp -d "/tmp/otel-contrib.XXXXXX") || exit 1
     trap "rm -fr ${TMPDIR}" EXIT
@@ -73,13 +77,15 @@ if [ -n "${OTEL_TAG}" ]; then
         exit 1
     fi
 fi
-if [ -n "${TAG}" ]; then
-    validate_tag "${TAG}" || exit $?
-    TAG_FOUND=$(git tag --list "${TAG}")
-    if [[ ${TAG_FOUND} = "${TAG}" ]] ; then
-        printf "Tag %s already exists\n" "${TAG}"
+if [ -n "${CONTRIB_TAG}" ]; then
+    validate_tag "${CONTRIB_TAG}" || exit $?
+    TAG_FOUND=$(git tag --list "${CONTRIB_TAG}")
+    if [[ ${TAG_FOUND} = "${CONTRIB_TAG}" ]] ; then
+        printf "Tag %s already exists in this repo\n" "${CONTRIB_TAG}"
         exit 1
     fi
+else
+    CONTRIB_TAG=${OTEL_TAG}  # if contrib_tag not specified, but OTEL_TAG is, then set it to OTEL_TAG
 fi
 
 cd "$(dirname "$0")"
@@ -91,10 +97,7 @@ if ! git diff --quiet; then \
     exit 1
 fi
 
-declare BRANCH_NAME=pre_release_${TAG}
-if [ -z "${TAG}" ]; then
-    BRANCH_NAME=bump_otel_${OTEL_TAG}
-fi
+declare -r BRANCH_NAME=pre_release_${CONTRIB_TAG}
 
 patch_gomods() {
     local pkg_=$1
@@ -120,8 +123,8 @@ if [ -n "${OTEL_TAG}" ]; then
     patch_gomods go.opentelemetry.io/otel "${OTEL_TAG}"
 fi
 
-if [ -n "${TAG}" ]; then
-    patch_gomods go.opentelemetry.io/contrib "${TAG}"
+if [ -n "${CONTRIB_TAG}" ]; then
+    patch_gomods go.opentelemetry.io/contrib "${CONTRIB_TAG}"
 fi
 
 git diff
@@ -131,10 +134,11 @@ make lint
 # Add changes and commit.
 git add .
 make ci
-declare COMMIT_MSG="Prepare for releasing $TAG"
-if [ -z "${TAG}" ]; then
-    COMMIT_MSG="Bumping otel version to ${OTEL_TAG}"
+declare COMMIT_MSG=""
+if [ -n "${OTEL_TAG}" ]; then
+    COMMIT_MSG+="Bumping otel version to ${OTEL_TAG}"
 fi
+COMMIT_MSG+=".  Prepare for releasing ${CONTRIB_TAG}"
 git commit -m "${COMMIT_MSG}"
 
 printf "Now run following to verify the changes.\ngit diff master\n"