diff --git a/.gitlab/merge_request_templates/Deprecations.md b/.gitlab/merge_request_templates/Deprecations.md index fc803152efbc2a3bd764f15a01372fc2ed50cce2..dcd5d79e0d07dcfb3e49068b2076b09b096d6e7b 100644 --- a/.gitlab/merge_request_templates/Deprecations.md +++ b/.gitlab/merge_request_templates/Deprecations.md @@ -30,8 +30,12 @@ Deprecation announcements can and should be created and merged into Docs at any --- -Please review the [guidelines for deprecations](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations), -as well as the process for [creating a deprecation entry](https://about.gitlab.com/handbook/marketing/blog/release-posts/#creating-a-deprecation-entry). +Please review: + +- The definitions of ["Deprecation", "End of Support", and "Removal"](https://docs.gitlab.com/ee/development/deprecation_guidelines/#terminology). +- The [guidelines for deprecations](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations). +- The process for [creating a deprecation entry](https://about.gitlab.com/handbook/marketing/blog/release-posts/#creating-a-deprecation-entry). + They are frequently updated, and everyone should make sure they are aware of the current standards (PM, PMM, EM, and TW). ## EM/PM release post item checklist diff --git a/.gitlab/merge_request_templates/Removals.md b/.gitlab/merge_request_templates/Removals.md index 0b7f1efe006636f29afac2bdf67aae41305d94a7..4801af2a1232b5ee5cceffdc0a9e20560f894a28 100644 --- a/.gitlab/merge_request_templates/Removals.md +++ b/.gitlab/merge_request_templates/Removals.md @@ -36,7 +36,10 @@ If the removal creates a [breaking change](https://about.gitlab.com/handbook/pro --- -Please review the [guidelines for removals](https://about.gitlab.com/handbook/marketing/blog/release-posts/#removals). +Please review: + +- The definitions of ["Deprecation", "End of Support", and "Removal"](https://docs.gitlab.com/ee/development/deprecation_guidelines/#terminology). +- The [guidelines for removals](https://about.gitlab.com/handbook/marketing/blog/release-posts/#removals). ## EM/PM release post item checklist diff --git a/data/deprecations/templates/example.yml b/data/deprecations/templates/example.yml index c69ebe2c7686b26eba997e33df485696302e5d5a..e5e04e5d216bad7432e27a97fb9a60db6b888df4 100644 --- a/data/deprecations/templates/example.yml +++ b/data/deprecations/templates/example.yml @@ -1,12 +1,11 @@ # This is a template for a feature deprecation. # -# Please refer to the deprecation guidelines to confirm your understanding of GitLab's definitions. +# Please refer to the deprecation guidelines to confirm your understanding of the +# definitions for "Deprecation", "End of Support", and "Removal": # https://docs.gitlab.com/ee/development/deprecation_guidelines/#terminology # # Deprecations must be announced at least three releases prior to removal. -# -# If an End of Support period applies, the announcement should be shared with GitLab Support -# in the `#spt_managers` on Slack and mention `@gitlab-com/support` in this MR. +# See the OPTIONAL END OF SUPPORT FIELDS section below if an End of Support period also applies. # # Breaking changes must happen in a major release. # @@ -35,10 +34,16 @@ END OF BODY COMMENT --> # -# OPTIONAL FIELDS +# OPTIONAL END OF SUPPORT FIELDS +# +# If an End of Support period applies, the announcement should be shared with GitLab Support +# in the `#spt_managers` channel in Slack, and mention `@gitlab-com/support` in this MR. # end_of_support_milestone: # (optional) Use "XX.YY" format. The milestone when support for this feature will end. end_of_support_date: # (optional) The date of the milestone release when support for this feature will end. +# +# OTHER OPTIONAL FIELDS +# tiers: # (optional - may be required in the future) An array of tiers that the feature is available in currently. e.g., [Free, Silver, Gold, Core, Premium, Ultimate] documentation_url: # (optional) This is a link to the current documentation page image_url: # (optional) This is a link to a thumbnail image depicting the feature diff --git a/data/removals/templates/example.yml b/data/removals/templates/example.yml index 3674583cd7d47c4eec6ca8ec2b6a14b7c168185a..8d7d694be268a2ba0e36dc870a55c42cdbfbf4b9 100644 --- a/data/removals/templates/example.yml +++ b/data/removals/templates/example.yml @@ -32,8 +32,6 @@ # # OPTIONAL FIELDS # - end_of_support_milestone: # (optional) Use "XX.YY" format. The milestone when support for this feature will end. - end_of_support_date: # (optional) The date of the milestone release when support for this feature will end. tiers: # (optional - may be required in the future) An array of tiers that the feature is available in currently. e.g., [Free, Silver, Gold, Core, Premium, Ultimate] documentation_url: # (optional) This is a link to the current documentation page image_url: # (optional) This is a link to a thumbnail image depicting the feature diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md index f0364f60d38168abe1456ab77abb512e16a00e8a..1e9d3ebda77dce04cec3b257040bed30a21c5fcb 100644 --- a/doc/development/deprecation_guidelines/index.md +++ b/doc/development/deprecation_guidelines/index.md @@ -11,16 +11,23 @@ to GitLab features. ## Terminology +<!-- +If updating these definitions, be sure to update them in the handbook as well: +https://about.gitlab.com/handbook/product/gitlab-the-product/#definitions +--> + **Deprecation**: +- Required before ending support for a feature or removing a feature. - Feature not recommended for use. - Development restricted to Priority 1 / Severity 1 bug fixes. - Will be removed in a future major release. -- Begins after a deprecation announcement outlining an end-of-support date. +- Begins after a deprecation announcement outlining an end-of-support or removal date. - Ends after the end-of-support date or removal date has passed. **End of Support**: +- Optional step before removal. - Feature usage strongly discouraged. - No support or fixes provided. - No longer tested internally. @@ -28,6 +35,10 @@ to GitLab features. - Begins after an end-of-support date has passed. - Ends after all relevant code has been removed. +[Announcing an End of Support period](https://about.gitlab.com/handbook/marketing/blog/release-posts/#announcing-an-end-of-support-period) +should only be used in special circumstances and is not recommended for general use. +Most features should be deprecated and then removed. + **Removal**: - Feature usage impossible.