|
| 1 | +# Releasing NNF Software |
| 2 | + |
| 3 | +## NNF Software Overview |
| 4 | + |
| 5 | +The following repositories comprise the NNF Software and each have their own versions. There is a |
| 6 | +hierarchy, since `nnf-deploy` packages the individual components together using submodules. |
| 7 | + |
| 8 | +Each component under `nnf-deploy` needs to be released first, then `nnf-deploy` can be updated to |
| 9 | +point to those release versions, then `nnf-deploy` itself can be updated and released. |
| 10 | + |
| 11 | +The documentation repo (NearNodeFlash/NearNodeFlash.github.io) is released separately and is not |
| 12 | +part of `nnf-deploy`, but it should match the version number of `nnf-deploy`. Release this like the |
| 13 | +other components. |
| 14 | + |
| 15 | +- [NearNodeFlash/nnf-deploy](https://github.com/NearNodeFlash/nnf-deploy) |
| 16 | + |
| 17 | + - [DataWorkflowServices/dws](https://github.com/DataWorkflowServices/dws) |
| 18 | + - [HewlettPackard/lustre-csi-driver](https://github.com/HewlettPackard/lustre-csi-driver) |
| 19 | + - [NearNodeFlash/lustre-fs-operator](https://github.com/NearNodeFlash/lustre-fs-operator) |
| 20 | + - [NearNodeFlash/nnf-mfu](https://github.com/NearNodeFlash/nnf-mfu) |
| 21 | + - [NearNodeFlash/nnf-ec](https://github.com/NearNodeFlash/nnf-ec) |
| 22 | + - [NearNodeFlash/nnf-sos](https://github.com/NearNodeFlash/nnf-sos) |
| 23 | + - [NearNodeFlash/nnf-dm](https://github.com/NearNodeFlash/nnf-dm) |
| 24 | + - [NearNodeFlash/nnf-integration-test](https://github.com/NearNodeFlash/nnf-integration-test) |
| 25 | + |
| 26 | +- [NearNodeFlash/NearNodeFlash.github.io](https://github.com/NearNodeFlash/NearNodeFlash.github.io) |
| 27 | + |
| 28 | +## Overview of release-all tool |
| 29 | + |
| 30 | +`release-all.sh` automates most of the steps of releasing NNF software and adds additional checks for common issues. |
| 31 | + |
| 32 | +## Assumptions |
| 33 | + |
| 34 | +- `master` or `main` branch for each repository contains **tested** software and documentation ready to be released. |
| 35 | +- You've installed the GitHub CLI tool, `gh`. |
| 36 | + - This tool requires a GH_TOKEN environment variable containing a `repo` scope classic token. |
| 37 | + |
| 38 | +## Steps |
| 39 | + |
| 40 | +### Run the steps in this order |
| 41 | + |
| 42 | +> **Note:** You almost always want to use the -R option to focus the `phase` activity to a specific repo. |
| 43 | +
|
| 44 | +0. **List Repos:** Get the ordered list of repo names to use with -R option in subsequent steps. This is referred to as `repo-list` |
| 45 | + > **Pro tip:** Keep this list in a separate window for easy viewing |
| 46 | + ./release-all.sh -L |
| 47 | + |
| 48 | +1. **Check Vendoring:** For each repo's master/main branch; determine whether any of them need to be re-vendored. |
| 49 | + > **Note:** Ensure each repo is error-free before proceeding to the next repo in `repo-list` |
| 50 | +
|
| 51 | + ```bash |
| 52 | + For each repo in `repo-list` |
| 53 | + ./release-all.sh -P master -R $repo |
| 54 | + ``` |
| 55 | + |
| 56 | +2. **Create Trial Release Branch:** Create the new release branch, merge master/main to that release branch, but don't push it yet. The point of this step is to look for merge conflicts between master/main and the release branch. |
| 57 | +
|
| 58 | + ```bash |
| 59 | + For each repo in `repo-list` |
| 60 | + ./release-all.sh -P release -R $repo |
| 61 | + ``` |
| 62 | +
|
| 63 | +3. **Generate Release:** For each repo in `repo-list`, proceed through the following steps in sequence before moving on to the next repo. |
| 64 | + > **Note:** The next steps use the gh(1) GitHub CLI tool and require a GH_TOKEN environment variable containing a 'repo' scope classic token. |
| 65 | + 1. If the **Create Trial Release Branch** had no errors: |
| 66 | +
|
| 67 | + ```bash |
| 68 | + ./release-all.sh -P release-push -R <repo> |
| 69 | + ``` |
| 70 | +
|
| 71 | + 2. If **Create Trial Release Branch** was unable to auto merge, manually fix and merge the release branch and re-run this phase on that existing branch: |
| 72 | +
|
| 73 | + ```bash |
| 74 | + cd workingspace/repo |
| 75 | + # Manually merge the changes from master/main to the release branch |
| 76 | + go mod tidy |
| 77 | + go mod vendor |
| 78 | + git status # confirm all issues have been address |
| 79 | + git add <all affected files> |
| 80 | + git commit -s # take the default commit message, don't bother editing it. |
| 81 | + ``` |
| 82 | + |
| 83 | + Then re-run this phase on this branch, telling the tool to pick up where you left off: |
| 84 | + |
| 85 | + ```bash |
| 86 | + USE_EXISTING_WORKAREA=1 ./release-all.sh -P release-push -R <repo> |
| 87 | + ``` |
| 88 | + |
| 89 | + 3. Create PR for the pushed release branch: |
| 90 | + |
| 91 | + ```bash |
| 92 | + ./release-all.sh -P create-pr -R <repo> |
| 93 | + ``` |
| 94 | + |
| 95 | + 3. Merge PR for the pushed release branch: |
| 96 | + **Note: Do NOT manually merge the PR, let `release-all.sh` merge it.** |
| 97 | + |
| 98 | + ```bash |
| 99 | + ./release-all.sh -P merge-pr -R <repo> |
| 100 | + ``` |
| 101 | + |
| 102 | + 4. Tag the release: |
| 103 | + |
| 104 | + ```bash |
| 105 | + ./release-all.sh -P tag-release -R <repo> |
| 106 | + ``` |
| 107 | + |
| 108 | +## Finalize the release notes |
| 109 | + |
| 110 | +Finalize the release by updating the `nnf-deploy` release notes to include the release notes from all submodules that were modified by this release. Do this after the release steps have been completed for all repositories, including the NearNodeFlash.github.io repository. |
| 111 | + |
| 112 | +1. Generate complete release notes for the specified `nnf-deploy` release for review: |
| 113 | +**Note: If this release does not include a new release of the NearNodeFlash.github.io docs, then specify `-D` to skip the docs.** |
| 114 | + |
| 115 | + ```bash |
| 116 | + ./final-release-notes.sh -r $NNF_RELEASE [-D] |
| 117 | + ``` |
| 118 | + |
| 119 | +2. Generate and commit the release notes to the specified `nnf-deploy` release: |
| 120 | + |
| 121 | + ```bash |
| 122 | + ./final-release-notes.sh -r $NNF_RELEASE -C [-D] |
| 123 | + ``` |
| 124 | + |
| 125 | +## Compare release manifests |
| 126 | + |
| 127 | +Compare the new NNF release manifest to a previous NNF release manifest. This can be useful for a variety of purposes. For example, this is a quick way to check for any problems in the release or to see which submodules were updated in the release. |
| 128 | + |
| 129 | +```console |
| 130 | +./compare-releases.sh v0.1.6 v0.1.7 |
| 131 | +``` |
| 132 | + |
| 133 | +The output: |
| 134 | + |
| 135 | +```console |
| 136 | +Manifest diffs for v0.1.6 to v0.1.7 are in workingspace/manifest-v0.1.6-to-v0.1.7.diff |
| 137 | +``` |
| 138 | +
|
| 139 | +Peruse the release manifest differences: |
| 140 | +
|
| 141 | +```console |
| 142 | +less workingspace/manifest-v0.1.6-to-v0.1.7.diff |
| 143 | +``` |
| 144 | +
|
| 145 | +Quickly see which submodules were updated between the releases: |
| 146 | +
|
| 147 | +```console |
| 148 | +grep image: workingspace/manifest-v0.1.6-to-v0.1.7.diff |
| 149 | +``` |
| 150 | +
|
| 151 | +Quickly determine the scope of the differences between the releases: |
| 152 | +
|
| 153 | +```console |
| 154 | +brew install patchutils diffstat |
| 155 | +lsdiff workingspace/manifest-v0.1.6-to-v0.1.7.diff |
| 156 | +diffstat workingspace/manifest-v0.1.6-to-v0.1.7.diff |
| 157 | +``` |
0 commit comments