Refine process and documentation for Breaking Changes, Deprecations and Removals
Problem(s)
As experienced during the 14.0 release post, there continue to be inconsistencies in PM's interpretation of the documented processes for deprecations and removals.
- The difference between deprecation and removal appears to be not well understood. This leads to items being placed in the deprecation section even though they should be in the removal section.
- Our templates don't use ISO dates, which leads to the inconsistent rendering of dates
- Process is manual
- The language used is inconsistent and we are not specific enough as to what is deprecated or removed.
- We use different tense in RP items (have been removed, is removed, will be removed etc.)
- I am not sure semantic versioning is well understood.
- Clarity and consistency in communication. Both in the release post summary and the linked issue. Example in comments below.
- SSOT for GitLab policy on breaking changes, deprecations, removals.
Current documentation on deprecations/removals
- https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations
- https://about.gitlab.com/handbook/marketing/blog/release-posts/#removals
- https://about.gitlab.com/handbook/product/gitlab-the-product/#deprecating-and-removing-features
- GitLab release and maintenance policy
- Deprecation guidelines
- Omnibus Deprecation Policy
Brainstorm on terminology and policy
Terminology
Breaking Changes: GitLab definition goes here. MR
Deprecation: Deprecation is the process of flagging/marking/announcing that a feature is scheduled for removal in a future version of GitLab.
- This is the current definition. Do we need to revise? In other words, our current language choice communicates to our user community that we don't simply deprecate a feature and leave it in the product but that we are going to remove that feature at some point in time.
Removal: Removal is the process of actually removing a feature that was previously deprecated.
GitLab Policy:
Breaking Changes:
-
A Breaking Change can occur when you intentionally plan to change or remove functionality or even result when you add new features.
-
It is the responsibility of the PM and EM for a category to carefully consider the risk and impact of introducing a breaking change as they can severely disrupt customers.
-
If you have determined that you are introducing a breaking change, you must notify the user community and customers. This means including a deprecation notice in the monthly release post as soon as possible.
-
The linked issue must have clear language describing the change and the impact to users.
Other links
NFS Executive summary SSOT: https://docs.google.com/document/d/1UpHjUDnPzbbDlOatShYu-tR_IV85mI-w5y8ftbG9KIA/edit#heading=h.dtc495iz20ge
Release post guidance video: https://www.youtube.com/watch?v=9gy7tg94j7s
To do
@DarrenEastman Making sure our overall policies and documentation in Docs are clear and align with any major decisions coming out of NFS:
-
Review NFS outcome/decisions. -
Do the first pass of content updates as you see fit, tagging in @fzimmer @fseifoddini @mjwood @sarahwaldner for review/feedback on MRs -
Attend NFS retro (2021-07-19) -
Collaborate with @sarahwaldner to ensure documentation in Docs related to deprecations/removals gets updated to align and be clarified if needed. (We want everything to be aligned to these NFS outcomes) -
If needed, do another pass up Docs updates, tagging in @fzimmer @fseifoddini @mjwood @sarahwaldner for review/feedback on MRs
@DarrenEastman Making sure our product handbook page is clear and aligns to GitLab policies and documentation in Docs:
-
Review NFS outcome/decisions. -
Do a first pass to update the product handbook page to have clear definitions of deprecations (breaking vs non-breaking) and removals (breaking vs non-breaking) as well as links to any relevant documentation throughout the engineering handbook and/or Docs, tagging in @fzimmer @fseifoddini @mjwood @sarahwaldner for review/feedback on MRs -
Include a brief (less than 3 min) video overview clarifying deprecations, removals, and breaking changes (NOT specific to the release post-process-- just clarifying what they are for the product and how they affect users) -
If needed, do another pass on content updates (including updating any referenced videos), tagging in @fzimmer @fseifoddini @mjwood @sarahwaldner for review/feedback on MRs
@DarrenEastman Making sure our release post page is clear and aligns to the product handbook page.
-
Do a first pass to update the release post page to align with and link to product handbook pages and Docs pages, tagging in @fzimmer @fseifoddini @mjwood @sarahwaldner for review/feedback on MRs -
Consider updating and/or unifying the deprecation/removals yml templates we currently use to simplify the process -
Consider if this video https://www.youtube.com/watch?v=9gy7tg94j7s which is linked to on the release post page needs to be updated
-
@mjwood Making the initial creation of deprecation/ MRs during the release post process easier for PMs/EMs
-
Investigate leverage the release post item generator to auto-generate MRs for deprecations and removals -
Share findings with @twoodham and @fseifoddini @sam.white to align and help update release post-process as needed
@sam.white Making the content replication process of deprecations easier
-
Explore options with @csouthard as a consultant on release post and Ruby -
Share findings with @mjwood and @fseifoddini @twoodham to align and help inform release post item generator efforts as needed
@fseifoddini
-
Work with @mkarampalas to add links to new content generated above to the Product L&D as appropriate
@fseifoddini @DarrenEastman
-
Do clear communication out to the cross-functional team via PM Weekly, Engineering updates channels suggested here and consider AMAs.