OPRUN-3021: Improve README

README.md

@@ -1,3 +1,16 @@
 # operator-framework-olm
 
-This repository is a monorepo superset of the projects that comprises the Operator Lifecycle Manager runtime and tooling for use with Openshift.
+This repository is a monorepo superset of the projects that comprises the
+Operator Lifecycle Manager runtime and tooling for use with Openshift.
+
+The upstream projects are:
+* [api](https://github.com/operator-framework/api)
+* [operator-registry](https://github.com/operator-framework/operator-registry)
+* [operator-lifecycle-manager](https://github.com/operator-framework/operator-lifecycle-manager)
+
+These projects are located in the `staging` directory. Changes to the
+contents of the `staging` directory need to be made upstream first (links
+above), and then downstreamed to this repository.
+
+Please refer to the [scripts README.md](scripts/README.md) to learn how to
+downstream commits from those projects to this repo.

scripts/README.md

@@ -2,4 +2,94 @@
 
 All of the staged repositories live in the top level `staging` directory.
 
-Note: the process for porting upstream commits downstream is outlined in the [OLM downstreaming guide](https://docs.google.com/document/d/139yXeOqAJbV1ndC7Q4NbaOtzbSdNpcuJan0iemORd3g/edit#).
+The downstreaming process is complex and helper scripts have been written
+to facilitate downstreaming.
+
+## Assumptions
+
+The helper scripts assume that the upstream remote repos are configured
+as follows:
+```
+git remote add api https://github.com/operator-framework/api
+git remote add operator-registry https://github.com/operator-framework/operator-registry
+git remote add operator-lifecycle-manager https://github.com/operator-framework/operator-lifecycle-manager
+```
+The [sync.sh](sync.sh) script will automatically create these
+remote repositories.
+
+## Bulk Sync
+
+To sync all current changes from upstream, simply run the sync script:
+```sh
+scripts/sync.sh
+```
+
+This script may pause at certain points to ask the user to examine
+command failures or possible regressions. Please open another terminal
+and review the state of the workspace before continuing the script.
+
+When the script completes, it will have created a branch whose name is
+the current date (formatted: `sync-YYYY-MM-DD`).
+
+If the `sync.sh` script fails, please refer to
+[[1](https://spaces.redhat.com/display/OOLM/Downstream+to+operator-framework-olm)]
+for continuation proceedures.
+
+Before this branch can be used to create a PR, run the following:
+```sh
+make -k verify
+```
+If there are any diffs or modified files, these need to be added to 
+your branch as either a separate commit (e.g. headline: `Run make verify`),
+or amended to the last commit of the branch.
+
+Once `make -k verify` is resolved, create a PR from this sync branch.
+
+
+## Targeted Sync
+
+To sync a subset of commits from the upstream repositories (i.e. critical
+bugfix), create a new working sync branch. Then create a `sync.cherrypick`
+file in the repositry root directory with the repos and commit SHAs.
+
+The format of the cherrypick file is:
+```
+<order> <repo> <commit-SHA>
+```
+
+For example:
+```
+1 api 0123456789abcdef0123456789abcdef01234567
+2 operator-lifecycle-manager 123456789abcdef0123456789abcdef012345678
+3 operator-lifecycle-manager 23456789abcdef0123456789abcdef0123456789
+```
+Do _not_ commit the cherrypick file, it is a temporary working file that
+is ignored by `git`.
+
+Then run the following:
+```sh
+scripts/sync_pop_candidate.sh -a sync
+```
+The commits in the `sync.cherrypick` file will be applied in the specified
+order.
+
+Even if you only have a single commit, this procedure will follow the same
+process that `sync.sh` does, to ensure no steps are missed.
+
+Before this branch can be used to create a PR, run the following:
+```sh
+make -k verify
+```
+If there are any diffs or modified files, these need to be added to 
+your branch as either a separate commit (e.g. headline: `Run make verify`),
+or amended to the last commit of the branch.
+
+Once `make -k verify` is resolved, create a PR from this working sync branch.
+
+## TODO
+
+* Add `make verify` to the `sync_pop_candidate.sh` and/or `sync.sh` scripts.
+
+## References
+1. [Downstream to operator-framework-olm](https://spaces.redhat.com/display/OOLM/Downstream+to+operator-framework-olm)
+2. [OLM downstreaming guide](https://docs.google.com/document/d/139yXeOqAJbV1ndC7Q4NbaOtzbSdNpcuJan0iemORd3g/edit#) (old)

scripts/sync.sh

@@ -69,4 +69,26 @@ main() {
     check_local_branch_commit_diff
 }
 
+script_help() {
+    cat <<EOF
+USAGE
+    scripts/sync.sh
+
+DESCRIPTION
+    Use this script to bulk sync from the upstream repositories.
+
+    There are no arguments to this script.
+
+    Refer to the README.md file for additional information.
+EOF
+    exit 1
+}
+
+# no arguments are required, look for any help-type arguments and print out help
+for var in "$@"; do
+    if [ "${var}" == "-h" -o "${var}" == "--help" ]; then
+        script_help
+    fi
+done
+
 main

scripts/sync_get_candidates.sh

@@ -1,5 +1,26 @@
 #!/usr/bin/env bash
 
+if [ $# -eq 0 ]; then
+    cat <<EOF
+USAGE
+    scripts/sync_get_candidates.sh <remote>
+
+OPTIONS
+    <remote>   Remote repository to search for commits
+
+DESCRIPTION
+    This script is used to automatically create cherrypick files for use
+    by the sync_pop_candidate.sh script. This script is called by the
+    sync.sh script to gather the commits to be part of the downsteam
+    sync.
+
+    Refer to the README.md file for additional information.
+EOF
+    exit 1
+fi
+
+
+
 set -o errexit
 set -o pipefail
 

scripts/sync_pop_candidate.sh

@@ -1,12 +1,38 @@
 #!/usr/bin/env bash
 
+if [ $# -eq 0 ]; then
+    cat <<EOF
+USAGE
+    scripts/sync_pop_candidate.sh [-a] <cherry-pick>
+
+OPTIONS
+    -a            Apply all changes from the <cherry-pick>
+    <cherry-pick> Filename (without .cherrypick extension) from which
+                  commits are selected to be synced
+
+DESCRIPTION
+    Use this script to sync a selection of commits from the upstream
+    repositories. This script is called by the sync.sh script to perform
+    the actual downstream sync.
+
+    The <cherry-pick> file is the basename of a file with a .cherrypick
+    extension. Usually, it is the name of a remote repository, but can
+    be any file that follows the .cherrypick format.
+
+    Refer to the README.md file for additional information.
+EOF
+    exit 1
+fi
+
 set -o errexit
 set -o pipefail
 #set -x
 
 ROOT_DIR=$(dirname "${BASH_SOURCE[@]}")/..
 # shellcheck disable=SC1091
 source "${ROOT_DIR}/scripts/common.sh"
+RED=$(tput setaf 1)
+RESET=$(tput sgr0)
 
 pop_all=false
 
@@ -88,7 +114,9 @@ function pop() {
     if ! git diff --quiet HEAD^ "${subtree_dir}"/go.mod; then
         git diff HEAD^ "${subtree_dir}"/go.mod
         pushd "${subtree_dir}"
-        echo "Running BASH subshell: go.mod has changed, check for regressions!"
+        echo ""
+        echo -e "Pausing script: ${RED}go.mod has changed, check for regressions!${RESET}"
+        echo "Use another terminal window"
         echo -n '<ENTER> to continue, ^C to quit: '
         read
         popd
@@ -99,15 +127,19 @@ function pop() {
     # 3. Ammend commit
     # 4. Remove from cherrypick set
     if ! make vendor; then
-        echo "Running BASH subshell: fix make vendor"
+        echo ""
+        echo -e "Pausing script: ${RED}fix make vendor{$RESET}"
+        echo "Use another terminal window"
         echo -n '<ENTER> to continue, ^C to quit: '
         read
     fi
     git add "${subtree_dir}" "${ROOT_GENERATED_PATHS[@]}"
     git status
     git commit --amend --allow-empty --no-edit --trailer "Upstream-repository: ${remote}" --trailer "Upstream-commit: ${rc}"
     if ! make manifests; then
-        echo "Running BASH subshell: fix make manifests"
+        echo ""
+        echo -e "Pausing script: ${RED}fix (or ignore) make manifests${RESET}"
+        echo "Use another terminal window"
         echo -n '<ENTER> to continue, ^C to quit: '
         read
     fi