From 91f8ae6c57f2e9b57e9d7ef448a0c61333386424 Mon Sep 17 00:00:00 2001 From: Adam Kaplan Date: Tue, 20 Feb 2024 15:16:58 -0500 Subject: [PATCH 1/4] SHIP-0038: Release Branching and Backports Provisional enhancement proposal to outline Shipwright's strategy for release branching and applying backports. The proposal's goal is to let sub-projects issue patch releases for bug fixes and security advisories. This is accomplished using a release branch name convention and updates to project release processes. Future iterations of this proposal will identify specific changes to be made in our existing release tooling. These updates will also describe how to apply these procedures retroactively to the `v0.12.0` releases of the following sub-projects: - build - operator - cli Signed-off-by: Adam Kaplan --- ships/0038-release-branching-backports.md | 200 ++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 ships/0038-release-branching-backports.md diff --git a/ships/0038-release-branching-backports.md b/ships/0038-release-branching-backports.md new file mode 100644 index 0000000..ac7c533 --- /dev/null +++ b/ships/0038-release-branching-backports.md @@ -0,0 +1,200 @@ + + +--- +title: release-branching-backports +authors: + - "@adambkaplan" +reviewers: + - "@apoorvajagtap" + - "@HeavyWombat" +approvers: + - "@qu1queee" + - "@SaschaSchwarze0" +creation-date: 2024-02-20 +last-updated: 2024-02-20 +status: provisional +see-also: + - https://github.com/shipwright-io/community/issues/85 + - https://github.com/shipwright-io/build/issues/1496 +replaces: [] +superseded-by: [] +--- + +# Release Branching and Backports + +## Release Signoff Checklist + +- [ ] Enhancement is `implementable` +- [ ] Design details are appropriately documented from clear requirements +- [ ] Test plan is defined +- [ ] Graduation criteria for dev preview, tech preview, GA +- [ ] User-facing documentation is created in [docs](/docs/) + +## Open Questions [optional] + +TBD as we iterate through the enhancement proposal lifecycle. + +## Summary + +Proposed release process changes for Shipwright projects so we can issue candidate +releases and provide backports for high-impact bug fixes/security advisories. + +## Motivation + +As the community provides stronger promises of stability in its projects, end users +and downstream distributions may not be able to wait for new upstream releases to +receive important bug fixes or security patches. Backporting is a common practice in +mature open source projects to provide these fixes without introducing new features +or other potential breaking changes. + +### Goals + +- Define processes and procedures Shipwright projects should use when creating a + release with respect to code branching. +- Define processes for applying bug fixes and security advisories to prior release + versions. +- Apply the backport process to the v0.12.0 release of the Shipwright build, cli, + and operator projects. + +### Non-Goals + +- Identify which bugs and security advisories are eligible for backport moving + forward. +- Apply the backport process to "alpha" maturity projects in Shipwright (ex: + triggers). +- Docs/website content strategy for released versions. +- Apply backport process to v0.11.0 and earlier. +- Prescribe a cadence for feature and bugfix releases. + +## Proposal + +Shipwright projects will continue to use the `main` branch for feature +development. When the project maintainers decide to create a release, they **MUST** +create a branch that adheres to the `release-vX.Y` naming convention. `X.Y` +represents the semantic _major_ and _minor_ version of the given release, +respectively. + +Release tags and artifacts for a given `X.Y` version **MUST** be created from the +respective `release-vX.Y` release branch. Releases **MUST** use a valid semantic +version when tagging or versioning artifacts, of the format `vX.Y.Z`. Projets +**MAY** append a hyphen to indicate a release candidate or other form of "pre- +release" version, in accorance with the SemVer 2.0 specification. For example, +`v0.13.0-rc2` can be used to represent version 0.13.0, _release candidate 2_. +CI checks to merge code in the the `main` branch **MUST** also be run against code +in release branches. Other measures applied to `main` branches (ex: branch +protection rules) **MUST** also be applied to release branches. + +All code changes **SHOULD** be merged into the `main` branch before being applied +to a previous release branch, or a release branch that is issuing release +candidates. Merging directly into a release branch without an equivalent code +change in the `main` branch is allowed at sole the discretion of project +maintainers. Once code is merged in `main`, it is eligible to be backported to an +appropriate release branch using `git cherry-pick` or equivalent commands. + +Backport code changes **SHOULD** be merged into release branches in descending +semantic version order if the code change should be applied to more than one release +version. This ensures upgrades from one patch version to the next minor version do +not introduce regressions with respect to bugs or security fixes. For example, if +the `release-v0.13` branch is issuing release candidates, and a bug fix for the +release needs to be backported to `release-v0.12`, code should merge in the +following order: + +1. Merge fix to `main` +2. Cherry pick to `release-v0.13` +3. Cherry pick to `release-v0.12` _after_ code merges in `release-v0.13`. + +Merging out of semantic version order **MAY** be done at the discretion of project +maintainers, especially in situations that involve security advisories with +"Critical" severity ratings. + +### User Stories [optional] + +- As a maintainer of a Shipwright distribution, I want Important/Critical severity + security advisories to be backported to a `v0.12.z` release stream so that I can + patch security vulnerabilities without introducing new features or breaking + changes. +- As a cluster admin / architect deploying Shipwright to my engineering teams, I + want to receive bug fixes for `v0.12.z` releases so that I don't need to wait for + a new feature upstream to receive bug fixes and security advisories. + +### Implementation Notes + +**Note:** *Section not required until feature is ready to be marked 'implementable'.* + +TBD - requires investigation into the following: + +- Current release script assumptions with respect to branch names. +- Current CI assumptions with respect to branch names. +- Applying the process "retroactively" to build, cli, and operator repos. + +### Test Plan + +TBD + +**Note:** *Section not required until targeted at a release.* + +``` +Consider the following in developing a test plan for this enhancement: + +- Will there be e2e and integration tests, in addition to unit tests? +- How will it be tested in isolation vs with other components? + +No need to outline all of the test cases, just the general strategy. Anything that would count as +tricky in the implementation and anything particularly challenging to test should be called out. + +All code is expected to have adequate tests (eventually with coverage expectations). +``` + +### Release Criteria + +TBD - ideally this is introduced to release `v0.13.0` and applied retroactively to +`v0.12.z`. + +#### Removing a deprecated feature [if necessary] + +Not Applicable + +#### Upgrade Strategy [if necessary] + +TBD + +### Risks and Mitigations + +TBD once the proposal is flushed out. + +``` +What are the risks of this proposal and how do we mitigate? Think broadly. For example, consider +both security and how this will impact the larger Shipwright ecosystem. + +How will security be reviewed and by whom? How will UX be reviewed and by whom? +``` + +## Drawbacks + +TBD once the implementation details are documented. + +``` +The idea is to find the best form of an argument why this enhancement should _not_ be implemented. +``` + +## Alternatives + +TBD as the enhancement proposal progresses through its lifecycle. + +``` +Similar to the `Drawbacks` section the `Alternatives` section is used to highlight and record other +possible approaches to delivering the value proposed by an enhancement. +``` + +## Infrastructure Needed [optional] + +TBD - this will likely require new GitHub actions, changes to existing GitHub +Actions, or enabling features in Prow (currently provided by OpenShift CI). + +## Implementation History + +- 2024-02-20: Inital proposal (`provisional`) From c748b5cc114edee0c6cf94e60d10ae8d39d50f10 Mon Sep 17 00:00:00 2001 From: Adam Kaplan Date: Thu, 22 Feb 2024 08:28:57 -0500 Subject: [PATCH 2/4] Correct typo Fix typo for "Projects" Co-authored-by: Sascha Schwarze --- ships/0038-release-branching-backports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ships/0038-release-branching-backports.md b/ships/0038-release-branching-backports.md index ac7c533..88b72bc 100644 --- a/ships/0038-release-branching-backports.md +++ b/ships/0038-release-branching-backports.md @@ -80,7 +80,7 @@ respectively. Release tags and artifacts for a given `X.Y` version **MUST** be created from the respective `release-vX.Y` release branch. Releases **MUST** use a valid semantic -version when tagging or versioning artifacts, of the format `vX.Y.Z`. Projets +version when tagging or versioning artifacts, of the format `vX.Y.Z`. Projects **MAY** append a hyphen to indicate a release candidate or other form of "pre- release" version, in accorance with the SemVer 2.0 specification. For example, `v0.13.0-rc2` can be used to represent version 0.13.0, _release candidate 2_. From df5fdef867d31cd22db5ff0c787162a2b2320336 Mon Sep 17 00:00:00 2001 From: Adam Kaplan Date: Thu, 22 Feb 2024 10:41:09 -0500 Subject: [PATCH 3/4] Updates from feedback - Replace `v0.12.z` references with "most recent released version." - Mark LTS and backports to older releases out of scope. - Clarify that we should have at most two branches accepting backports at a given moment in time. Maintainers may backport further at their discretion (ex: a Critical CVE). Signed-off-by: Adam Kaplan --- ships/0038-release-branching-backports.md | 28 +++++++++++++---------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/ships/0038-release-branching-backports.md b/ships/0038-release-branching-backports.md index 88b72bc..0505b4e 100644 --- a/ships/0038-release-branching-backports.md +++ b/ships/0038-release-branching-backports.md @@ -15,7 +15,7 @@ approvers: - "@qu1queee" - "@SaschaSchwarze0" creation-date: 2024-02-20 -last-updated: 2024-02-20 +last-updated: 2024-02-22 status: provisional see-also: - https://github.com/shipwright-io/community/issues/85 @@ -55,10 +55,10 @@ or other potential breaking changes. - Define processes and procedures Shipwright projects should use when creating a release with respect to code branching. -- Define processes for applying bug fixes and security advisories to prior release - versions. -- Apply the backport process to the v0.12.0 release of the Shipwright build, cli, - and operator projects. +- Define processes for applying bug fixes and security advisories to the most recent + released version. +- Apply the backport process to current released versions of the Shipwright build, + cli, and operator projects. ### Non-Goals @@ -67,8 +67,9 @@ or other potential breaking changes. - Apply the backport process to "alpha" maturity projects in Shipwright (ex: triggers). - Docs/website content strategy for released versions. -- Apply backport process to v0.11.0 and earlier. +- Apply backport process to older released versions. - Prescribe a cadence for feature and bugfix releases. +- Establish long term support (LTS) versioning and backport processes. ## Proposal @@ -107,19 +108,22 @@ following order: 2. Cherry pick to `release-v0.13` 3. Cherry pick to `release-v0.12` _after_ code merges in `release-v0.13`. -Merging out of semantic version order **MAY** be done at the discretion of project -maintainers, especially in situations that involve security advisories with -"Critical" severity ratings. +In general, there **SHOULD** be at most two branches accepting backports (the most +recent release, and a current release candidate). Maintainers **MAY** accept +backports to prior releases at their discretion, for instance if a security advisory +with "Critical" severity impacts multiple prior releases. Merging out of semantic +version order **MAY** likewise be done at the discretion of project maintainers in +such situations. ### User Stories [optional] - As a maintainer of a Shipwright distribution, I want Important/Critical severity - security advisories to be backported to a `v0.12.z` release stream so that I can + security advisories to be backported to the most recent release so that I can patch security vulnerabilities without introducing new features or breaking changes. - As a cluster admin / architect deploying Shipwright to my engineering teams, I - want to receive bug fixes for `v0.12.z` releases so that I don't need to wait for - a new feature upstream to receive bug fixes and security advisories. + want to receive bug fixes for the most recent release so that I don't need to wait + for a new feature release upstream to receive bug fixes and security advisories. ### Implementation Notes From a5f7478c61526a6ad228ac497850a7e3891f00a9 Mon Sep 17 00:00:00 2001 From: Adam Kaplan Date: Thu, 22 Feb 2024 18:20:07 -0500 Subject: [PATCH 4/4] Fix Spelling Fix typos from review Co-authored-by: Enrique Encalada --- ships/0038-release-branching-backports.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ships/0038-release-branching-backports.md b/ships/0038-release-branching-backports.md index 0505b4e..95a0523 100644 --- a/ships/0038-release-branching-backports.md +++ b/ships/0038-release-branching-backports.md @@ -83,7 +83,7 @@ Release tags and artifacts for a given `X.Y` version **MUST** be created from th respective `release-vX.Y` release branch. Releases **MUST** use a valid semantic version when tagging or versioning artifacts, of the format `vX.Y.Z`. Projects **MAY** append a hyphen to indicate a release candidate or other form of "pre- -release" version, in accorance with the SemVer 2.0 specification. For example, +release" version, in accordance with the SemVer 2.0 specification. For example, `v0.13.0-rc2` can be used to represent version 0.13.0, _release candidate 2_. CI checks to merge code in the the `main` branch **MUST** also be run against code in release branches. Other measures applied to `main` branches (ex: branch @@ -201,4 +201,4 @@ Actions, or enabling features in Prow (currently provided by OpenShift CI). ## Implementation History -- 2024-02-20: Inital proposal (`provisional`) +- 2024-02-20: Initial proposal (`provisional`)