From 6d83c390f06635615705e0ab87507bb421879017 Mon Sep 17 00:00:00 2001 From: Blake Devcich <89158881+bdevcich-hpe@users.noreply.github.com> Date: Tue, 13 Jun 2023 16:35:56 -0500 Subject: [PATCH] Add release process documentation; change container RFC to published (#74) --- docs/repo-guides/readme.md | 5 + docs/repo-guides/release-nnf-sw/readme.md | 170 ++++++++++++++++++++++ docs/rfcs/0002/readme.md | 2 +- mkdocs.yml | 38 ++--- 4 files changed, 196 insertions(+), 19 deletions(-) create mode 100644 docs/repo-guides/readme.md create mode 100644 docs/repo-guides/release-nnf-sw/readme.md diff --git a/docs/repo-guides/readme.md b/docs/repo-guides/readme.md new file mode 100644 index 0000000..52ffe73 --- /dev/null +++ b/docs/repo-guides/readme.md @@ -0,0 +1,5 @@ +# Repo Guides + +## Management + +* [Releasing NNF Software](release-nnf-sw/readme.md) diff --git a/docs/repo-guides/release-nnf-sw/readme.md b/docs/repo-guides/release-nnf-sw/readme.md new file mode 100644 index 0000000..52d3c0c --- /dev/null +++ b/docs/repo-guides/release-nnf-sw/readme.md @@ -0,0 +1,170 @@ +--- +authors: Blake Devcich +categories: release, repo +--- + +# Releasing NNF Software + +## NNF Software Overview + +The following repositories comprise the NNF Software and each have their own versions. There is a +hierarchy, since `nnf-deploy` packages the individual components together using submodules. + +Each component under `nnf-deploy` needs to be released first, then `nnf-deploy` can be updated to +point to those release versions, then `nnf-deploy` itself can be updated and released. + +The documentation repo (NearNodeFlash/NearNodeFlash.github.io) is released separately and is not +part of `nnf-deploy`, but it should match the version number of `nnf-deploy`. Release this like the +other components. + +- [NearNodeFlash/nnf-deploy](https://github.com/NearNodeFlash/nnf-deploy) + - [HewlettPackard/dws](https://github.com/HewlettPackard/dws) + - [NearNodeFlash/lustre-fs-operator](https://github.com/NearNodeFlash/lustre-fs-operator) + - [HewlettPackard/lustre-csi-driver](https://github.com/HewlettPackard/lustre-csi-driver) + - [NearNodeFlash/nnf-mfu](https://github.com/NearNodeFlash/nnf-mfu) + - [NearNodeFlash/nnf-sos](https://github.com/NearNodeFlash/nnf-sos) + - [NearNodeFlash/nnf-dm](https://github.com/NearNodeFlash/nnf-dm) +- [NearNodeFlash/NearNodeFlash.github.io](https://github.com/NearNodeFlash/NearNodeFlash.github.io) + +[nnf-ec](https://github.com/NearNodeFlash/nnf-ec) is vendored in as part of `nnf-sos` and does not +need to be released separately. + +## Primer + +This document is based on the process set forth by the [DataWorkflowServices Release +Process](https://dataworkflowservices.github.io/v0.0.1/repo-guides/create-a-release/readme/). +Please read that as a background for this document before going any further. + +## Requirements + +To create tags and releases, you will need maintainer or admin rights on the repos. + +## Release Each Component In `nnf-deploy` + +You'll first need to create releases for each component contained in `nnf-deploy`. This section +describes that process. + +Each release branch needs to be updated with what is on master. To do that, we'll need the latest +copy of master, and it will ultimately be merged to the `releases/v0` branch via a Pull Request. +Once merged, an annotated tag is created and then a release. + +Each component has its own version number that needs to be incremented. **Make sure you change the +version numbers** in the commands below to match the new version for the component. The `v0.0.3` is +just an example. + +1. Ensure your branches are up to date: + + ```shell + git checkout master + git pull + git checkout releases/v0 + git pull + ``` + +2. Create a branch to merge into the release branch: + + ```shell + git checkout -b release-v0.0.3 + ``` + +3. Merge in the updates from the `master` branch. There **should not** be any conflicts, but it's + not unheard of. Tread carefully if there are conflicts. + + ```shell + git merge master + ``` + +4. Verify that there are no differences between your branch and the master branch: + + ```shell + git diff master + ``` + + If there are any differences, they must be trivial. Some READMEs may have extra lines at the + end. + +5. For `lustre-csi-driver` and `lustre-fs-operator`, there are additional files that need to track + the version number as well, which allow them to be installed with `kubectl apply -k`. + + a. For `lustre-fs-operator`, update `config/manager/kustomization.yaml` with the correct + version. + + b. For `lustre-csi-driver`, update `deploy/kubernetes/base/kustomization.yaml` and + `charts/lustre-csi-driver/values.yaml` with the correct version. + +6. Create a Pull Request from your branch and **target the release branch**. When merging the Pull +Request, **you must use a Merge Commit.** + + !!! note + + **Do not** Rebase or Squash! Those actions will remove the records that Git uses to determine which + commits have been merged, and then when the next release is created Git will treat everything + like a conflict. Additionally, this will cause auto-generated release notes to include the previous release. + +7. Once merged, update the release branch locally and then create an annotated tag: + + ```shell + git checkout releases/v0 + git tag -a v0.0.3 -m "Release v0.0.3" + git push origin --tags + ``` + +8. Now that there is a tag, a release can be created via the [GitHub CLI](https://cli.github.com/). + Alternatively, use the [Web UI](https://github.com/NearNodeFlash/nnf-dm/releases/new). + + ```bash + gh release create --generate-notes --verify-tag -p v0.0.3 -t "Release v0.0.3" + ``` + +9. Repeat this process for each remaining component. + +## Release `nnf-deploy` + +Once the individual components are released, we need to update the submodules and +`config/repositories.yaml` in the **master** branch before we start on the release branch. This makes +sure that everything is now current on master. + +1. Update the submodules on master: + + ```shell + git checkout master + git pull + ./update.sh + ``` + +2. Update `config/repositories.yaml` and update the referenced versions for: + + a. `lustre-csi-driver` + + b. `lustre-fs-operator` + + c. `nnf-mfu` + +3. Commit the changes and open a Pull Request against the `master` branch. + +4. Once merged, follow steps 1-3 from the previous section to update the release branch with master. + +5. There will be conflicts on the submodules after step 3. This is expected. We will update the + submodules to the new tags and then commit the changes. If each tag was committed properly, the + following command can do this for you: + + ```shell + git submodule foreach 'git checkout `git describe --match="v*" HEAD`' + ``` + + Verify that each submodule is now at the proper tagged version. + + ```shell + git submodule status + ``` + +6. Do a `git add` for each of the submodules. + +7. Run `go mod tidy` and then `make`. Do another `git add` for any changes, particularly`go.mod` and/or `go.sum`. + +8. Verify that `git status` is happy with `nnf-deploy` and then finalize the merge from master by + doing a `git commit`. + +9. Follow steps 6-8 from the previous section to finalize the release of `nnf-deploy`. + +The software is now released! diff --git a/docs/rfcs/0002/readme.md b/docs/rfcs/0002/readme.md index 2e28679..134aa9f 100644 --- a/docs/rfcs/0002/readme.md +++ b/docs/rfcs/0002/readme.md @@ -1,6 +1,6 @@ --- authors: Blake Devcich -state: discussion +state: published --- # Rabbit storage for containerized applications diff --git a/mkdocs.yml b/mkdocs.yml index a8bad15..d0cfaec 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,27 +1,29 @@ site_name: NNF -site_description: 'Near Node Flash' +site_description: "Near Node Flash" docs_dir: docs/ -repo_name: 'NearNodeFlash/NearNodeFlash.github.io' +repo_name: "NearNodeFlash/NearNodeFlash.github.io" repo_url: https://github.com/NearNodeFlash/NearNodeFlash.github.io -copyright: '© Copyright 2023 Hewlett Packard Enterprise Development LP' +copyright: "© Copyright 2023 Hewlett Packard Enterprise Development LP" nav: - Home: index.md - - 'User Guides': - - guides/index.md - - 'Initial Setup': 'guides/initial-setup/readme.md' - - 'Compute Daemons': 'guides/compute-daemons/readme.md' - - 'Data Movement': 'guides/data-movement/readme.md' - - 'Firmware Upgrade': 'guides/firmware-upgrade/readme.md' - - 'High Availability Cluster': 'guides/ha-cluster/readme.md' - - 'RBAC for Users': 'guides/rbac-for-users/readme.md' - - 'Storage Profiles': 'guides/storage-profiles/readme.md' - - 'User Containers': 'guides/user-containers/readme.md' - - 'RFCs': - - rfcs/index.md - - 'Rabbit Request For Comment Process': 'rfcs/0001/readme.md' - - 'Rabbit Storage For Containerized Applications': 'rfcs/0002/readme.md' + - "User Guides": + - guides/index.md + - "Initial Setup": "guides/initial-setup/readme.md" + - "Compute Daemons": "guides/compute-daemons/readme.md" + - "Data Movement": "guides/data-movement/readme.md" + - "Firmware Upgrade": "guides/firmware-upgrade/readme.md" + - "High Availability Cluster": "guides/ha-cluster/readme.md" + - "RBAC for Users": "guides/rbac-for-users/readme.md" + - "Storage Profiles": "guides/storage-profiles/readme.md" + - "User Containers": "guides/user-containers/readme.md" + - "RFCs": + - rfcs/index.md + - "Rabbit Request For Comment Process": "rfcs/0001/readme.md" + - "Rabbit Storage For Containerized Applications": "rfcs/0002/readme.md" + - "Repo Admin Guides": + - "Releasing NNF Software": "repo-guides/release-nnf-sw/readme.md" theme: - name: 'material' + name: "material" custom_dir: overrides features: - content.code.copy