chore(docs): update the release process docs (openebs#3059)

* chore(docs): update naming and release docs Signed-off-by: kmova <kiran.mova@mayadata.io> * chore(docs): update release management process docs Signed-off-by: kmova <kiran.mova@mayadata.io> * fix the order of release tagging Signed-off-by: kmova <kiran.mova@mayadata.io>
meghanareddy-k · Jun 13, 2020 · 32324e0 · 32324e0
1 parent 21fdcf8
commit 32324e0
Show file tree

Hide file tree

Showing 6 changed files with 143 additions and 49 deletions.
diff --git a/README.md b/README.md
@@ -17,7 +17,7 @@ Some key aspects that make OpenEBS different compared to other traditional stora
 - Built using the micro-services architecture like the applications it serves. OpenEBS is itself deployed as a set of containers on Kubernetes worker nodes. Uses Kubernetes itself to orchestrate and manage OpenEBS components
 - Built completely in userspace making it highly portable to run across any OS/platform
 - Completely intent-driven, inheriting the same principles that drive the ease of use with Kubernetes
-- OpenEBS supports a range of storage engines so that developers can deploy the storage technology appropriate to their application design objectives. Distributed applications like Cassandra can use the LocalPV engine for lowest latency writes. Monolithic applications like MySQL and PostgreSQL can use the ZFS engine (cStor) for resilience. Streaming applications like Kafka can use the NVMe engine [MayaStor](https://github.com/openebs/MayaStor) for best performance in edge environments. Across engine types, OpenEBS provides a consistent framework for high availability, snapshots, clones and manageability.
+- OpenEBS supports a range of storage engines so that developers can deploy the storage technology appropriate to their application design objectives. Distributed applications like Cassandra can use the LocalPV engine for lowest latency writes. Monolithic applications like MySQL and PostgreSQL can use the ZFS engine (cStor) for resilience. Streaming applications like Kafka can use the NVMe engine [Mayastor](https://github.com/openebs/Mayastor) for best performance in edge environments. Across engine types, OpenEBS provides a consistent framework for high availability, snapshots, clones and manageability.
 
 OpenEBS itself is deployed as just another container on your host and enables storage services that can be designated on a per pod, application, cluster or container level, including:
 - Automate the management of storage attached to the Kubernetes worker nodes and allow the storage to be used for Dynamically provisioning OpenEBS PVs or Local PVs.
@@ -77,7 +77,7 @@ The status of various storage engines that power the OpenEBS Persistent Volumes
 | Jiva | stable | Best suited for running Replicated Block Storage on nodes that make use of ephemeral storage on the Kubernetes worker nodes |
 | cStor | beta | A preferred option for running on nodes that have Block Devices. Recommended option if Snapshot and Clones are required |
 | Local Volumes | beta | Best suited for Distributed Application that need low latency storage - direct-attached storage from the Kubernetes nodes. |
-| MayaStor | alpha | A new storage engine that operates at the efficiency of Local Storage but also offers storage services like Replication. Development is underway to support Snapshots and Clones. |
+| Mayastor | alpha | A new storage engine that operates at the efficiency of Local Storage but also offers storage services like Replication. Development is underway to support Snapshots and Clones. |
 
 For more details, please refer to [OpenEBS Documentation](https://docs.openebs.io/docs/next/quickstart.html).
 

diff --git a/RELEASE.md b/RELEASE.md
@@ -0,0 +1,16 @@
+# Release Process
+
+OpenEBS follows a monthly release cadence. The process is as follows:
+
+The scope of the release is determined by:
+- contributor availability, 
+- pending items listed in the [roadmap](./ROADMAP.md) and 
+- the [issues filed by the community](https://github.com/search?q=is%3Aissue+is%3Aopen+label%3Aproject%2Fcommunity+org%3Aopenebs&type=Issues). 
+
+1. The release scope is published and tracked using [GitHub Projects](https://github.com/orgs/openebs/projects). To maintain monthly release cadence, the project tracker is setup with indicative milestones leading up to freezing the feature development in the 3rd week, the remaining days are used to run e2e and fix any issues found by e2e or community. 
+1. At the start of the release cycle, one of the contributor takes on the role of release manager and works with the OpenEBS Maintainers to co-ordinate the release activities.  
+1. Contributors sync-up over [community calls and slack](./community/) to close on the release tasks. Release manager runs the community calls for a given release. In the community call, the risks are identified and mitigated by seeking additional help or by pushing the task to next release.
+1. The various release management tasks are explained in the [release process document](./contribute/process/release-management.md).
+1. OpenEBS release is made via GitHub. Once all the components are released, [Change Summary](https://github.com/openebs/openebs/wiki) is updated and [openebs/openebs](https://github.com/openebs/openebs/releases) repo is tagged with the release. 
+1. OpenEBS release in announced on [all Community reach out channels](./community/).
+1. The release tracker GitHub project is closed
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -31,7 +31,7 @@ While the following are planned items, a higher priority is given to usability a
   * Enhance the discovery probes to support partitions, lvms and so forth
   * Support Prometheus exporter on block device metrics
   * Add gRPC API layer around NDM capabilities
-* MayaStor 
+* [Mayastor](https://github.com/openebs/Mayastor)
   * Replication across multiple nodes
   * Integration and end-to-end tests
   * Setup CI

diff --git a/community/README.md b/community/README.md
@@ -13,11 +13,14 @@ If that does not answer your questions, or if you think you found a bug, please
 
 ## Contact
 
-- **Slack:** Join our Slack Channels. 
-  - `Kubernetes Slack`, please join the [#openebs channel](https://kubernetes.slack.com/messages/openebs/)
-  - `Cloud Native Slack`, please join the [#openebs channel](https://cloud-native.slack.com/messages/openebs/)
-
-- **Forum:** Subscribe to our [user forum](https://lists.cncf.io/g/cncf-openebs-users) or [announcement list](https://lists.cncf.io/g/cncf-openebs-announcements).
+- **Slack:** [Join OpenEBS community on Kubernetes Slack](https://kubernetes.slack.com).
+    - Already signed up? 
+      * Head to our user discussions at [#openebs](https://kubernetes.slack.com/messages/openebs/)
+      * Head to our contributor discussions at [#openebs-dev](https://kubernetes.slack.com/messages/openebs-dev/)
+
+- **Forum:** Subscribe to our email lists: 
+  - [user forum](https://lists.cncf.io/g/cncf-openebs-users) or 
+  - [announcement list](https://lists.cncf.io/g/cncf-openebs-announcements).
 
 - **Twitter:** Follow us [@openebs](https://twitter.com/openebs).
 
@@ -51,6 +54,4 @@ We have monthly meeting every first Tuesday at 9.30AM PT over [Zoom](https://zoo
 
 This meeting focuses on reviewing the [current roadmap](https://github.com/openebs/openebs/blob/master/ROADMAP.md) and direction of the project or general questions from the broader community. 
 
-
-
 Go back to [**Contributing to OpenEBS**](../CONTRIBUTING.md).
diff --git a/contribute/process/release-management.md b/contribute/process/release-management.md
@@ -4,79 +4,156 @@ OpenEBS follows a monthly release cadence. The scope of the release is determine
 
 ## Overview
 
-* Release Manager is identified at the beginning of each release from the contributor community, who will work with one of the maintainers of the OpenEBS project. Release manager is responsible for tracking the scope, coordinating with various stack holders and helping root out the risks to the release as early as possible. Release manager uses the [Daily Standup](https://github.com/openebs/openebs/tree/master/community#regular-standup-and-release-cadence-meetings) and the [Release Tracker](https://github.com/orgs/openebs/projects) to help everyone stay focused on the release.
+* Release Manager is identified at the beginning of each release from the contributor community, who will work with one of the maintainers of the OpenEBS project. Release manager is responsible for tracking the scope, coordinating with various stack holders and helping root out the risks to the release as early as possible. Release manager uses the [Daily Standup](https://github.com/openebs/openebs/tree/master/community#daily-standup-and-release-cadence-meetings) and the [Release Tracker](https://github.com/orgs/openebs/projects) to help everyone stay focused on the release.
+
 * Each release has the following important milestones that have organically developed to help maintain the monthly release cadence.
   * First Week - Release planning is completed with leads identified for all the features targeted for the release. At the end of the first week, there should not be any "To do" items in the release tracker. If there are no leads available, the "To do" items will be pushed to the next release backlog. It is possible that some of the contributors will continue to work on the items that may not make it into current release, but will be pushed into the upcoming release.
   * Second Week - Depending on the feature status - alpha, beta or stable, the various tasks from development, review, e2e and docs are identified. Any blockers in terms of design or implementation are discussed and mitigated.
-  * Third Week - Release branch is created and the first Release candidate build is made available. Post this stage only bug fixes are accepted into the release. Upgrades are tested. Staging documentation is updated. CI Pipelines are automated with new tests.
+  * Third Week - [Release branch](#release-branch) is created and the first [Release candidate container images](#release-tagging) are made available. Post this stage only bug fixes are accepted into the release. Upgrades are tested. Staging documentation is updated. CI Pipelines are automated with new tests.
   * Fourth Week - Release notes are prepared. The final RC build is pushed to Dogfooding and beta testing with some of the users. The installers are updated. Release, Contributor and User Documentation are published.
   * Fifth Week - Post release activities like pushing the new release to the partner charts like Rancher Catalog, Amazon marketplace and so forth are worked on.
 
-## Release Candidate Verification Checklist
 
-Every release has release candidate builds that are created starting from the third week into the release. These release candidate builds help to freeze the scope and maintain the quality of the release. The release candidate builds will go through:
-- Platform Verification
-- Regression and Feature Verification Automated tests.
-- Exploratory testing by QA engineers
-- Strict security scanners on the container images
-- Upgrade from previous releases
-- Beta testing by users on issues that they are interested in.
-- Dogfooding on OpenEBS workload and e2e infrastructure clusters
+## Release Branch
+
+OpenEBS Components are developed on several different code repositories. Active development happens on the master branch. When all the development activities scoped for a given release are completed or the deadline for code-freeze (third week) has approached, a release branch is created from the master. The branch is named after major and minor version of the release. Example for `1.10.0`, release, the release branch will be `v1.10.x`
 
-If any issues are found during the above stages, they are fixed and a new release candidate builds are generated.
+Post creating the release branch, if any critical fixes are identified for the release, then the fixes will be pushed to master as well as cherry-picked into the corresponding release branches. 
 
-Once all the above tests are completed, a main release tagged images, helm and operator YAMLs are published.
+Release Branch will be used for tagging the release belonging to a given major and minor version and all the subsequent patch releases. For example, `v1.10.0`, `v1.10.1` and so forth will be done from `v1.10.x` release branch. 
+
+Release branches need to be created for the following repositories:
+- openebs/jiva
+- openebs/libcstor
+- openebs/cstor
+- openebs/istgt
+- openebs/external-storage
+- openebs/maya
+- openebs/velero-plugin
+- openebs/cstor-csi
+- openebs/jiva-operator
+- openebs/jiva-csi
+- openebs/api
+- openebs/cstor-operators
+- openebs/upgrade
+
+The following repositories currently follow a custom release version.
+- openebs/node-disk-manager
+- openebs/zfs-localpv
+
+The following repositories are under active development and releases are created from master branch.
+- openebs/Mayastor
+- openebs/linux-utils
+- openebs/rawfile-localpv
+- openebs/monitor-pv
+
+To verify that release branches are created, you can run the following script:
+
+```
+git clone https://github.com/openebs/charts
+cd charts
+git checkout gh-pages
+
+cd scripts/release
+./check-release-branch.sh <release-branch>
+```
 
 ## Release Tagging
 
 OpenEBS Components are released as container images with versioned tags.
 
 OpenEBS components are spread across various repositories. Creating a release tag on the repository will trigger the build, integration tests and pushing of the docker image to [docker hub](https://hub.docker.com/u/openebs) and [quay](https://quay.io/organization/openebs/) container repositories.
 
-The format of the release tag is either "Release-Name-RC1" or "Release-Name" depending on whether the tag is a release candidate or a release. (Example: 1.0.0-RC1 is a GitHub release tag for OpenEBS release candidate build. 1.0.0 is the release tag that is created after the release criteria are satisfied by the release candidate builds.)
+The format of the GitHub release tag is either "Release-Name-RC1" or "Release-Name" depending on whether the tag is a release candidate or a release. (Example: v1.0.0-RC1 is a GitHub release tag for OpenEBS release candidate build. v1.0.0 is the release tag that is created after the release criteria are satisfied by the release candidate builds.)
+
+Each repository has the automation scripts setup to push the container images to docker and quay container repositories. The container image tag will be derived from GitHub release tag by truncating `v` from the release name. (Example: v1.0.0-RC1 will create container images for 1.0.0-RC1).
 
-Each repository has the automation scripts setup to push in the container images to docker and quay container repositories.
+Once a release made on a repository, Travis will trigger the release on the dependent repositories. The release tree looks as follows:
 
-The release tags are applied in the following order:
 - openebs/linux-utils
-- openebs/libcstor
-- openebs/cstor
-- openebs/istgt
-- openebs/jiva
+  - openebs/jiva
+  - openebs/libcstor
+    - openebs/cstor
+      - openebs/istgt
+        - openebs/cstor-operators
+        - openebs/external-storage
+          - openebs/maya
+            - openebs/velero-plugin
+            - openebs/cstor-csi
+            - openebs/jiva-operator
+              - openebs/jiva-csi
+
+The following repositories currently follow a different release versioning than other components, so these are triggered parallely. 
 - openebs/node-disk-manager
-- openebs/external-storage
-- openebs/velero-plugin
-- openebs/maya
-- openebs/cstor-csi
-- openebs/jiva-csi
-- openebs/jiva-operator
 - openebs/zfs-localpv
+- openebs/Mayastor
+
+The following repositories are under active development and are not yet added into the release process. These needs to be manually tagged on-demand.
+- openebs/api
+- openebs/rawfile-localpv
+- openebs/monitor-pv
 
-Once the release is triggered, Travis build process has to be monitored. Once Travis builds are passed images are pushed to docker hub and quay.io. Images can be verified by going through docker hub and quay.io. Also the images shouldn't have any high level vulnerabilities.
+Once the release is triggered, Travis build process has to be monitored. Once Travis builds are passed, images are pushed to docker hub and quay.io. Images can be verified by going through docker hub and quay.io. Also the images shouldn't have any critical security vulnerabilities.
 Example:
 https://quay.io/repository/openebs/cstor-pool?tab=tags
 https://hub.docker.com/r/openebs/openebs-k8s-provisioner/tags
 
-Once a release is created on a repository, update the release description with commit log. The following commands can be used:
-```
-git checkout <release-branch>
-git log --pretty=format:'- %s (%h) (@%an)' --date=short  --since="1 month"
-```
+## E2e Testing on Release Builds
 
-In case there are no changes, update it with "No changes"
+Each minor and major release comprises of one or more release candidate builds, followed by a final release. 
 
-For RC tags, update the commit log with changes since the last tag.
-For Release tag, update the commit log with changes since the last release tag. This will ideally be sum of all the commits from the RC tags.
+Release Candidate builds are started from the third week into the release cycle. These release candidate builds help to freeze the scope and maintain the quality of the release. A release branch is created prior to generating the first release candidate build. Any issues found during the verification of the release candidate build are fixed in the master and cherry-picked into the release branch, prior to next release candidate build or the release build. 
 
-## Final Release Checklist
-- There are no release blockers identified in the [Release Candidate Verification Checklist](#release-candidate-verification-checklist) on the final release tagged images.
+Once the release candidate or release images are generated, raise a [request for running e2e pipeline](https://github.com/openebs/e2e-tests/issues/new/choose) to kick-start the build validation via automated and manual e2e tests. 
+
+The e2e tests include the following:
+- Platform Verification
+- Regression and Feature Verification Automated tests.
+- Exploratory testing by QA engineers
+- Strict security scanners on the container images
+- Upgrade from previous releases
+- Beta testing by users on issues that they are interested in.
+- Dogfooding on OpenEBS workload and e2e infrastructure clusters
+
+Once all the above tests are completed successfully on release candidate builds, the final release build is triggered.  
+
+E2e tests are repeated on the final release build. 
+
+The status of the E2e on the release builds can be tracked in [openebs/e2e-tests](https://github.com/openebs/e2e-tests/issues?q=is%3Aissue+is%3Aopen+label%3Arelease-checklist)
+
+Once the release build validation is complete, helm and operator YAMLs are published to [openebs/charts](https://github.com/openebs/charts).
+
+
+## Release Checklist
+- All release blockers found by [e2e testing on Release Candidate builds](#e2e-testing-on-release-builds) are resolved.
 - The updated Install and Feature documentation are verified.
 - Release notes with changes summary, changelog are updated.
 - Verify that releases under each individual repository are updated with commit and CHANGELOG.
 - openebs-operator and helm charts are published.
 - Release is tagged on openebs/openebs repository.
 - Release is announced on slack, distribution lists and social media.
 
+## Generating Changelog and Release Summary
+
+- For each individual repositories:
+  * Update the Github releases with the commit log. The following commands can be used:
+
+    ```
+    git checkout <release-branch>
+    git log --pretty=format:'- %s (%h) (@%an)' --date=short  --since="1 month"
+    ```
+    In case there are no changes, update it with "No changes".
+
+    For RC tags, update the commit log with changes since the last tag.
+
+    For Release tag, update the commit log with changes since the last release tag. This will ideally be sum of all the commits from the RC tags.
+
+  * Raise a PR to update the CHANGELOG.md.
+
+- Create an aggregate Change Summary for the release under [openebs/wiki](https://github.com/openebs/openebs/wiki).
+
+- Create an Release Summary with highlights from the release that will be used with [openebs/releases](https://github.com/openebs/openebs/releases).
+
 ## Post Release Activities
 - Blogs on new features are published
 - Update the newsletter contents