Documentation: Add developer documentation on required stops
What does this MR do?
This merge request adds a new page into the development docs that more fully covers "required stop" - a major
.minor
version release that results in the need for a self-managed installation to pause at that release during an multi-version upgrade.
It's the first iteration for the development docs flowing out of discussions in the following issues:
- FY24Q2 Add examples of required upgrade stop to the product documentation
- Put in place measures to avoid addition/proliferation of GitLab upgrade path stops
It's meant to augment the current "Adding Required Stops" docs with a focus on avoiding stops outside of intentionally scheduled releases - and highlighting past causes of required stops.
Additional design considerations
- The first iteration focuses solely on going through the current set of required stops (outside of major releases) and briefly examining the cause of why it became a required stop as a learning/educational exercise.
- It's not meant to be prescriptive, it does not cover potential causes of future unscheduled stops, and it does not cover all of the kinds of deprecations and breaking changes that may cause a required stop (though it does link to version-specific considerations and deprecation items).
- It presumes that major releases are designed to be required stops for those not following a continuous deployment process, or staying with the current N -> N-2 maintenance releases.
- While groupdistribution owns the upgrade process there are no notes here from the distribution engineer perspective (outside of comments on the parent issue). This first iteration does not cover the of scenarios (usually dependency updates) distribution is called on to review to prevent a required stop - it only focuses on the causes for previous (non major release related) stops.
I'm on the fence about the value of prescriptive items, so that's why this focused solely on trying to briefly cover prior events in aggregate.
Thoughts for future iterations
- Having the teams involved in previous required stops write team-specific items relevant guidelines specific to their team (similar to how teams write up guidelines on breaking changes today) and linking those from the doc.
- Potential expansion of the discussion section on deprecations and breaking changes, so that major release related stops can be further minimized. ( Which may dovetail with: Clarify meaning and process of breaking changes from instance and admin perspective )
- Create new issues to actually discuss QA or other product tooling to put up process guardrails around items that cause required stops.
Related issues
Closes gitlab-org/distribution/team-tasks#1264 (closed)
Author's checklist
-
Optional. Consider taking the GitLab Technical Writing Fundamentals course. -
Follow the: -
If you're adding or changing the main heading of the page (H1), ensure that the product tier badge is added. -
If you are a GitLab team member, request a review based on: - The documentation page's metadata.
- The associated Technical Writer.
If you are a GitLab team member and only adding documentation, do not add any of the following labels:
~"frontend"
~"backend"
~"type::bug"
~"database"
These labels cause the MR to be added to code verification QA issues.
Reviewer's checklist
Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.
If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.
-
If the content requires it, ensure the information is reviewed by a subject matter expert. - Technical writer review items:
-
Ensure docs metadata is present and up-to-date. -
Ensure the appropriate labels are added to this MR. -
Ensure a release milestone is set. - If relevant to this MR, ensure content topic type principles are in use, including:
-
The headings should be something you'd do a Google search for. Instead of Default behavior
, say something likeDefault behavior when you close an issue
. -
The headings (other than the page title) should be active. Instead of Configuring GDK
, say something likeConfigure GDK
. -
Any task steps should be written as a numbered list. - If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
-
-
-
Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.