Skip to content

Commit 6a71523

Browse files
tmshorttmshort
committed
OPRUN-3021: Improve README
Add additional information to the README files. Add help for the sync scripts Signed-off-by: Todd Short <[email protected]>
1 parent 9a977fa commit 6a71523

File tree

5 files changed

+160
-5
lines changed

5 files changed

+160
-5
lines changed

‎README.md

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,16 @@
11
# operator-framework-olm
22

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

‎scripts/README.md

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,71 @@
22

33
All of the staged repositories live in the top level `staging` directory.
44

5-
Note: the process for porting upstream commits downstream is outlined in the [OLM downstreaming guide](https://docs.google.com/document/d/139yXeOqAJbV1ndC7Q4NbaOtzbSdNpcuJan0iemORd3g/edit#).
5+
The downstreaming process is complex and helper scripts have been written
6+
to facilitate downstreaming.
7+
8+
## Assumptions
9+
10+
The helper scripts assume that the upstream remote repos are configured
11+
as follows:
12+
```
13+
git remote add api https://github.com/operator-framework/api
14+
git remote add operator-registry https://github.com/operator-framework/operator-registry
15+
git remote add operator-lifecycle-manager https://github.com/operator-framework/operator-lifecycle-manager
16+
```
17+
The [sync.sh](sync.sh) script will automatically create these
18+
remote repositories.
19+
20+
## Bulk Sync
21+
22+
To sync all current changes from upstream, simply run the sync script:
23+
```sh
24+
scripts/sync.sh
25+
```
26+
27+
This script may pause at certain points to ask the user to examine
28+
command failures or possible regressions. Please open another terminal
29+
and review the state of the workspace before continuing the script.
30+
31+
When the script completes, it will have created a branch whose name is
32+
the current date (formatted: `sync-YYYY-MM-DD`). Create a PR from this
33+
sync branch.
34+
35+
If the script fails, please refer to [[1](https://spaces.redhat.com/display/OOLM/Downstream+to+operator-framework-olm)]
36+
for continuation proceedures.
37+
38+
## Targeted Sync
39+
40+
To sync a subset of commits from the upstream repositories (i.e. critical
41+
bugfix), create a new working sync branch. Then create a `sync.cherrypick`
42+
file in the repositry root directory with the repos and commit SHAs.
43+
44+
The format of the cherrypick file is:
45+
```
46+
<order> <repo> <commit-SHA>
47+
```
48+
49+
For example:
50+
```
51+
1 api 0123456789abcdef0123456789abcdef01234567
52+
2 operator-lifecycle-manager 123456789abcdef0123456789abcdef012345678
53+
3 operator-lifecycle-manager 23456789abcdef0123456789abcdef0123456789
54+
```
55+
Do _not_ commit the cherrypick file, it is a temporary working file that
56+
is ignored by `git`.
57+
58+
Then run the following:
59+
```sh
60+
scripts/sync_pop_candidate.sh -a sync
61+
```
62+
The commits in the `sync.cherrypick` file will be applied in the specified
63+
order.
64+
65+
Even if you only have a single commit, this procedure will follow the same
66+
process that `sync.sh` does, to ensure no steps are missed.
67+
68+
When done, create a PR from the working sync branch.
69+
70+
References:
71+
1. [Downstream to operator-framework-olm](https://spaces.redhat.com/display/OOLM/Downstream+to+operator-framework-olm)
72+
2. [OLM downstreaming guide](https://docs.google.com/document/d/139yXeOqAJbV1ndC7Q4NbaOtzbSdNpcuJan0iemORd3g/edit#) (old)

‎scripts/sync.sh

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,4 +69,26 @@ main() {
6969
check_local_branch_commit_diff
7070
}
7171

72+
script_help() {
73+
cat <<EOF
74+
USAGE
75+
scripts/sync.sh
76+
77+
DESCRIPTION
78+
Use this script to bulk sync from the upstream repositories.
79+
80+
There are no arguments to this script.
81+
82+
Refer to the README.md file for additional information.
83+
EOF
84+
exit 1
85+
}
86+
87+
# no arguments are required, look for any help-type arguments and print out help
88+
for var in "$@"; do
89+
if [ "${var}" == "-h" -o "${var}" == "--help" ]; then
90+
script_help
91+
fi
92+
done
93+
7294
main

‎scripts/sync_get_candidates.sh

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,26 @@
11
#!/usr/bin/env bash
22

3+
if [ $# -eq 0 ]; then
4+
cat <<EOF
5+
USAGE
6+
scripts/sync_get_candidates.sh <remote>
7+
8+
OPTIONS
9+
<remote> Remote repository to search for commits
10+
11+
DESCRIPTION
12+
This script is used to automatically create cherrypick files for use
13+
by the sync_pop_candidate.sh script. This script is called by the
14+
sync.sh script to gather the commits to be part of the downsteam
15+
sync.
16+
17+
Refer to the README.md file for additional information.
18+
EOF
19+
exit 1
20+
fi
21+
22+
23+
324
set -o errexit
425
set -o pipefail
526

‎scripts/sync_pop_candidate.sh

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,38 @@
11
#!/usr/bin/env bash
22

3+
if [ $# -eq 0 ]; then
4+
cat <<EOF
5+
USAGE
6+
scripts/sync_pop_candidate.sh [-a] <cherry-pick>
7+
8+
OPTIONS
9+
-a Apply all changes from the <cherry-pick>
10+
<cherry-pick> Filename (without .cherrypick extension) from which
11+
commits are selected to be synced
12+
13+
DESCRIPTION
14+
Use this script to sync a selection of commits from the upstream
15+
repositories. This script is called by the sync.sh script to perform
16+
the actual downstream sync.
17+
18+
The <cherry-pick> file is the basename of a file with a .cherrypick
19+
extension. Usually, it is the name of a remote repository, but can
20+
be any file that follows the .cherrypick format.
21+
22+
Refer to the README.md file for additional information.
23+
EOF
24+
exit 1
25+
fi
26+
327
set -o errexit
428
set -o pipefail
529
#set -x
630

731
ROOT_DIR=$(dirname "${BASH_SOURCE[@]}")/..
832
# shellcheck disable=SC1091
933
source "${ROOT_DIR}/scripts/common.sh"
34+
RED=$(tput setaf 1)
35+
RESET=$(tput sgr0)
1036

1137
pop_all=false
1238

@@ -88,7 +114,9 @@ function pop() {
88114
if ! git diff --quiet HEAD^ "${subtree_dir}"/go.mod; then
89115
git diff HEAD^ "${subtree_dir}"/go.mod
90116
pushd "${subtree_dir}"
91-
echo "Running BASH subshell: go.mod has changed, check for regressions!"
117+
echo ""
118+
echo -e "Pausing script: ${RED}go.mod has changed, check for regressions!${RESET}"
119+
echo "Use another terminal window"
92120
echo -n '<ENTER> to continue, ^C to quit: '
93121
read
94122
popd
@@ -99,15 +127,19 @@ function pop() {
99127
# 3. Ammend commit
100128
# 4. Remove from cherrypick set
101129
if ! make vendor; then
102-
echo "Running BASH subshell: fix make vendor"
130+
echo ""
131+
echo -e "Pausing script: ${RED}fix make vendor{$RESET}"
132+
echo "Use another terminal window"
103133
echo -n '<ENTER> to continue, ^C to quit: '
104134
read
105135
fi
106136
git add "${subtree_dir}" "${ROOT_GENERATED_PATHS[@]}"
107137
git status
108138
git commit --amend --allow-empty --no-edit --trailer "Upstream-repository: ${remote}" --trailer "Upstream-commit: ${rc}"
109139
if ! make manifests; then
110-
echo "Running BASH subshell: fix make manifests"
140+
echo ""
141+
echo -e "Pausing script: ${RED}fix (or ignore) make manifests${RESET}"
142+
echo "Use another terminal window"
111143
echo -n '<ENTER> to continue, ^C to quit: '
112144
read
113145
fi

0 commit comments

Comments
 (0)