diff --git a/.gitlab/merge_request_templates/Deprecations.md b/.gitlab/merge_request_templates/Deprecations.md
index af6073ee4df35548ab2f166aeb08e7b72bc983a4..5e16db1bde062db0ef97658e06f6f9672a2e7076 100644
--- a/.gitlab/merge_request_templates/Deprecations.md
+++ b/.gitlab/merge_request_templates/Deprecations.md
@@ -36,7 +36,9 @@ They are frequently updated, and everyone should make sure they are aware of the
## EM/PM release post item checklist
- [ ] Set yourself as the Assignee, meaning you are the DRI.
-- [ ] If the deprecation is a [breaking change](https://handbook.gitlab.com/handbook/product/gitlab-the-product/#breaking-changes), add label `breaking change`.
+- [ ] For [breaking changes](https://handbook.gitlab.com/handbook/product/gitlab-the-product/#breaking-changes):
+ - [ ] Add the `breaking change` label to the MR.
+ - [ ] If the breaking change affects GitLab.com, add `window` with a value of `1`, `2`, or `3`. The value represents the planned release window for GitLab.com, typically in the three weeks before the major release date. You should intentionally plan this window ahead of time. If you're not sure, ask `@swiskow`.
- [ ] Confirm this MR is labeled ~"release post item::deprecation"
- [ ] Follow the process to [create a deprecation YAML file](https://handbook.gitlab.com/handbook/marketing/blog/release-posts/#creating-the-announcement).
- [ ] Add reviewers by the 10th.
diff --git a/data/deprecations/18-0-graphql-removal.yml b/data/deprecations/18-0-graphql-removal.yml
index 8a374d733ec205544db46387e7fea5f361c41bd4..face54233b3679a0d90458981b82a34b6a18c39b 100644
--- a/data/deprecations/18-0-graphql-removal.yml
+++ b/data/deprecations/18-0-graphql-removal.yml
@@ -8,7 +8,6 @@
# and a link to the deprecation issue
reporter: dhershkovitch
stage: verify
- window: "2"
issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/424417
body: | # (required) Don't change this line.
The `previousStageJobsOrNeeds` field in GraphQL will be removed as it has been replaced by the `previousStageJobs` and `needs` fields.
diff --git a/data/deprecations/18-0-rate-limit-by-default.yml b/data/deprecations/18-0-rate-limit-by-default.yml
index a6872e1c2a9fac0ed9368279550d0cd1959a11a5..7b3459ee17d3cea2372b9c4787749c8f82005c32 100644
--- a/data/deprecations/18-0-rate-limit-by-default.yml
+++ b/data/deprecations/18-0-rate-limit-by-default.yml
@@ -8,7 +8,6 @@
# and a link to the deprecation issue
reporter: joshlambert
stage: systems
- window: "1"
issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/480914
impact: low # Can be one of: [critical, high, medium, low]
scope: instance # Can be one or a combination of: [instance, group, project]
diff --git a/data/deprecations/18-0-scan-execution-policy-action-limit.yml b/data/deprecations/18-0-scan-execution-policy-action-limit.yml
index c5b02fa405c3ad0404bdf08c4318753e44ac4ccd..8ad195889075d1baa8d1428fa2a31651a1a67f39 100644
--- a/data/deprecations/18-0-scan-execution-policy-action-limit.yml
+++ b/data/deprecations/18-0-scan-execution-policy-action-limit.yml
@@ -7,7 +7,6 @@
issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/472213
impact: low
scope: instance
- window: "3"
resolution_role: Maintainer
manual_task: true
body: |
diff --git a/data/deprecations/templates/example.yml b/data/deprecations/templates/example.yml
index bd15e7caea281e621e5da714c4635b059c2d2fa8..3ac4c1363f25e315e33735722c7512e239962c97 100644
--- a/data/deprecations/templates/example.yml
+++ b/data/deprecations/templates/example.yml
@@ -26,9 +26,8 @@
announcement_milestone: "XX.YY"
# Change breaking_change to false if needed.
breaking_change: true
- # The stage and GitLab username of the person reporting the change,
- # and a link to the deprecation issue
- reporter: exampleuser
+ window: # Can be [1, 2, or 3] - The window when the breaking change will be deployed on GitLab.com
+ reporter: exampleuser # The GitLab username of the person reporting the change
stage: stage
issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/000000
# Use the impact calculator https://gitlab-com.gitlab.io/gl-infra/breaking-change-impact-calculator/?
@@ -36,7 +35,6 @@
scope: # Can be one or a combination of: [instance, group, project]
resolution_role: # Can be one of: [Admin, Owner, Maintainer, Developer]
manual_task: # Can be true or false. Use this to denote whether a resolution action must be performed manually (true), or if it can be automated by using the API or other automation (false).
- window: # Can be "1", "2" or "3"
body: | # (required) Don't change this line.
<!-- START OF BODY COMMENT
diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md
index 45362c047970de4ff4befe470040017748dafc72..ab38300bd9740805745fe6355c02f790b7238911 100644
--- a/doc/development/deprecation_guidelines/index.md
+++ b/doc/development/deprecation_guidelines/index.md
@@ -100,6 +100,32 @@ Related Handbook pages:
- <https://handbook.gitlab.com/handbook/marketing/blog/release-posts/#deprecations-removals-and-breaking-changes>
- <https://handbook.gitlab.com/handbook/marketing/blog/release-posts/#update-the-deprecations-doc>
+## Update the breaking change windows documentation
+
+The [breaking change windows](../../update/breaking_windows.md)
+documentation is generated based on the `window` value in the YAML files located in
+[`gitlab/data/deprecations`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/data/deprecations).
+
+To update the breaking change windows page when a YAML file is added,
+edited, or removed:
+
+1. From the command line, go to your local clone of the [`gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab) project.
+1. Create, edit, or remove the YAML file under [`data/deprecations`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/data/deprecations).
+1. Compile the breaking change windows documentation:
+
+ ```shell
+ bin/rake gitlab:docs:compile_windows
+ ```
+
+1. If needed, you can verify the documentation is up to date with:
+
+ ```shell
+ bin/rake gitlab:docs:check_windows
+ ```
+
+1. Commit the updated documentation and push the changes.
+1. Create a merge request.
+
## Update the related documentation
When features are deprecated and removed, [update the related documentation](../documentation/styleguide/deprecations_and_removals.md).
diff --git a/doc/development/documentation/site_architecture/automation.md b/doc/development/documentation/site_architecture/automation.md
index b0402dfff5eb286202efcd078ca4df114633b5fa..67273cb8398daf25a3d36dec73fdaf71e112ad70 100644
--- a/doc/development/documentation/site_architecture/automation.md
+++ b/doc/development/documentation/site_architecture/automation.md
@@ -43,7 +43,8 @@ that are coded across multiple repositories.
|---|---|---|
| [All feature flags in GitLab](../../../user/feature_flags.md) | [Generated during docs build](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/raketasks.md#generate-the-feature-flag-tables) | [Technical Writing](https://handbook.gitlab.com/handbook/product/ux/technical-writing/) |
| [GitLab Runner feature flags](https://docs.gitlab.com/runner/configuration/feature-flags.html) | [Page source](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/ec6e1797d2173a95c8ac7f726bd62f6f110b7211/docs/configuration/feature-flags.md?plain=1#L39) | [Runner](https://handbook.gitlab.com/handbook/engineering/development/ops/verify/runner/) |
-| [Deprecations and removals by version](../../../update/deprecations.md) | [Deprecating GitLab features](../../deprecation_guidelines/index.md) | |
+| [Deprecations and removals by version](../../../update/deprecations.md) | [Update the deprecations and removals documentation](../../deprecation_guidelines/index.md#update-the-deprecations-and-removals-documentation) | |
+| [Breaking change windows](../../../update/breaking_windows.md) | [Update the breaking change windows documentation](../../deprecation_guidelines/index.md#update-the-breaking-change-windows-documentation) | |
| [GraphQL API resources](../../../api/graphql/reference/index.md) | [GraphQL API style guide](../../api_graphql_styleguide.md#documentation-and-schema) | [Import and Integrate](https://handbook.gitlab.com/handbook/engineering/development/dev/foundations/import-and-integrate/) |
| [Audit event types](../../../user/compliance/audit_event_types.md) | [Audit event development guidelines](../../audit_event_guide/index.md) | [Compliance](https://handbook.gitlab.com/handbook/engineering/development/sec/govern/compliance/) |
| [Available custom role permissions](../../../user/custom_roles/abilities.md) | [Generated by Rake task](https://gitlab.com/gitlab-org/gitlab/-/blob/master/tooling/custom_roles/docs/templates/custom_abilities.md.erb) | [Authorization](https://handbook.gitlab.com/handbook/product/categories/#authorization-group)|
diff --git a/doc/update/breaking_window.md b/doc/update/breaking_windows.md
similarity index 76%
rename from doc/update/breaking_window.md
rename to doc/update/breaking_windows.md
index e9343849a389d91861ed5f97bf1377df1861ad6c..68efd9d838c4392459f63d10b458b0e1416f0aeb 100644
--- a/doc/update/breaking_window.md
+++ b/doc/update/breaking_windows.md
@@ -25,7 +25,6 @@ This window takes place on April 21 - 23, 2025 from 09:00 UTC to 22:00 UTC.
| Deprecation | Impact | Stage | Scope |
|-------------|--------|-------|-------|
-| [Rate limits for common User, Project, and Group API endpoints](https://gitlab.com/gitlab-org/gitlab/-/issues/480914) | Low | Systems | Instance |
## Window 2
@@ -33,7 +32,6 @@ This window takes place on April 28 - 30, 2025 from 09:00 UTC to 22:00 UTC.
| Deprecation | Impact | Stage | Scope |
|-------------|--------|-------|-------|
-| [Remove `previousStageJobsOrNeeds` from GraphQL](https://gitlab.com/gitlab-org/gitlab/-/issues/424417) | | Verify | |
## Window 3
@@ -41,4 +39,3 @@ This window takes place on May 5 - 7, 2025 from 09:00 UTC to 22:00 UTC.
| Deprecation | Impact | Stage | Scope |
|-------------|--------|-------|-------|
-| [Limited `scan` actions in a scan execution policy](https://gitlab.com/gitlab-org/gitlab/-/issues/472213) | Low | Govern | Instance |
diff --git a/lib/tasks/gitlab/docs/compile_windows.rake b/lib/tasks/gitlab/docs/compile_windows.rake
index 1bf94d76066581f0d662153c6433d0626289f433..3bb244a44406ea8f5e17d5326c0f732c648e3402 100644
--- a/lib/tasks/gitlab/docs/compile_windows.rake
+++ b/lib/tasks/gitlab/docs/compile_windows.rake
@@ -1,6 +1,6 @@
# frozen_string_literal: true
-OUTPUT_FILE = 'doc/update/breaking_window.md'
+OUTPUT_FILE = 'doc/update/breaking_windows.md'
DEPRECATIONS_PATH = 'data/deprecations'
TARGET_MILESTONE = '18.0'
@@ -37,7 +37,7 @@ def write_metadata(file)
stage: none
group: none
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
- noindex: false
+ noindex: true
---
# Breaking change deployments on GitLab.com