From c93e6657c91f3b951c70a53ca9218d2b52e01e4e Mon Sep 17 00:00:00 2001 From: Mayra Cabrera Date: Fri, 16 Sep 2022 15:57:47 -0500 Subject: [PATCH] Update major version docs Updates major version documentation, also adds specific guidelines for release managers. --- general/major.md | 74 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 67 insertions(+), 7 deletions(-) diff --git a/general/major.md b/general/major.md index 0a2f82b4..120b4f39 100644 --- a/general/major.md +++ b/general/major.md @@ -1,14 +1,15 @@ # Major release -GitLab releases a new major version (for example, 12.0) [once per year](#frequency). +GitLab releases a new major version (for example, 15.0) [once per year](#frequency). A major release allows us to make breaking changes, for instance removing or changing (deprecating) existing APIs and functionalities. -## Handling deprecations +## General guidelines -[Deprecated items](https://about.gitlab.com/handbook/product/#deprecated-no-longer-maintained) -should be announced and, if necessary, replaced one or more minor releases +### Handling deprecations + +Deprecated items should be announced and, if necessary, replaced one or more minor releases in advance of the major release. For instance, when going from API v4 to v5, v5 will have to be active for at @@ -17,7 +18,7 @@ to deprecate an API over a single month, and an even longer time period might be (such as one major release for a new API version, or a span of a number of minor releases). -## New functionalities and APIs +### New functionalities and APIs New functionalities and APIs can freely be added at any time and should not be ported back. @@ -26,14 +27,14 @@ For instance, GitLab 8.16 introduced an API for time tracking. This adds to the API and will not break any integrations, so could be introduced in a minor update. -## Frequency +### Frequency Major releases will be scheduled for May 22 each year, by default. For more information, see our [maintenance policy](https://docs.gitlab.com/ee/policy/maintenance.html). -## Creating awareness +### Creating awareness People need to be aware of changes and deprecations. For each major or breaking change, consider: @@ -44,6 +45,65 @@ change, consider: customers transition. - Optionally reaching out to customers and/or external applications. +## Release managers guidelines + +When dealing with major releases, release managers should: + +* Open up an issue to set the expectations for the Engineering department, use the below template. + * This issue should be opened before the development cycle starts. +* Broadcast this issue: + * Add it to the Engineering week in review. + * Notify to different slack channels by using `/chatops run notify`. + * Ask Engineering Managers to broadcast the message to their team members by posting a message on `#eng-managers` Slack channel. +* Identify the guaranteed sha two working days earlier than usual. This sha is normally identified around the 15th, +for major releases, it's acceptable to identify it on the 13th. + +### Issue template + +* [15.0 example](https://gitlab.com/gitlab-com/gl-infra/delivery/-/issues/2279) + +
+Click to expand + +## What to expect? + + release preparation will begin earlier than normal to give release managers extra time to handle the additional work that we expect will come from merging lots of [breaking changes](https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&state=all&label_name[]=release%20post%20item%3A%3Adeprecation&label_name[]=breaking%20change). As always we're working to provide a safe release for our users on the 22nd. + +**We'll be identifying the guaranteed `sha` for release on **. This is working days earlier than most releases. This means that in the event of incidents or other issues affecting stability we may make the release from this `sha`. + +If you have a change that must make we recommend merging it in as soon as you can to be sure of making the release cut. + +In the days between and we will try to deploy as often as we can. Packages that are deployed to production and look stable may be included in [15.0]; though this cannot be guaranteed. + +## We need your help + +If you find something that has been merged when it shouldn't have been or [spot a bug please alert the release managers](https://about.gitlab.com/handbook/engineering/releases/#how-can-i-get-a-high-severity-bug-fix-released) in the `#releases` channel. + +## Want to keep up with the release steps? + +We'll be announcing the guaranteed `sha`, the candidate commit, stable branch creation, and the final commit for release in #releases, #development, #backend, #frontend and #quality Slack channels. You can also follow the steps in the [release issue](). + +## If you have questions + +Please feel free to ask process-related questions on this issue. For anything related to a specific MR or deployment please use the `#releases` Slack channel and ping `@release-managers` + +## Guidelines for merging changes into [15.0] + +1. Over-communicate breaking changes ahead of time. It's not too early to start, especially if a change requires active actions from our users. +1. Don't merge breaking changes that require communication before they are ready to be go live. You can assume that a merged change will be on GitLab.com in approximately 12 hours. If release managers have to block a package and revert something this will delay everyone's work by half a day. Half a day closer to the 22nd could make the difference between making it into or not. +1. Use feature flags if you want to control timing, but don't forget that it has to be removed, or defaulted to `true` in time for the release +1. When changing a feature flag, run the command from the `#production` channel to ensure maximum visibility +1. When merging an MR or changing a feature flag, the DRI for that change should also monitor afterwards to ensure it is operating as intended +1. Keep the support department in the loop, they will have more tickets due to breaking changes +1. Never assume dates in communications, we cannot ensure that a specific change will make it to GitLab.com on a specific day + +## References + +* [Deprecations](https://docs.gitlab.com/ee/update/deprecations.html) +* [Communications for breaking changes]() + +
+ --- [Return to Guides](../README.md#guides) -- GitLab