Remove the need for release managers to create/update upgrading guides
The RC workflow contains the following step:
Step 1: Create the "Update" guides
Each major release of GitLab needs a corresponding update guide with instructions on how to manually upgrade from the previous major release.
Note: GitLab CE and EE each have specific guides that need to be created. Make sure to do both!
Note: For the examples below, we're going to be using GitLab 8.2 as an example of the upcoming release, and 8.1 as an example of the previous release.
Currently this requires the following step:
- Set up an MR that creates this file, target
master
and add "Pick into X" - Merge the MR
- Cherry-pick the MR into the stable branch
Release managers are not aware of the exact update requirements for every version, and given the number of changes it's almost impossible for them to determine this after the changes have been introduced.
Since creating the guides ahead of time doesn't really work, I propose the following:
Instead of creating one document for every major/minor version, we have a single "Upgrading source installations" guideline, just like the "Installation from source" guideline. Whenever new steps are required, developers make the necessary changes in their merge requests. Since documentation is versioned per branch, one can find version specific guidelines by just changing the branch in the dropdown:
This wouldn't be more difficult than being linked to a directory in our Git repository and having to figure out which document you need to read yourself. At the same time, it makes our lives much easier because:
- Release managers don't have to create these guides and figure out what changes need to be made.
- We don't need any automation to (for example) create the guides ahead of time.
- Since the file always exists, the chances of merge conflicts (e.g. two MRs creating the same file) are less likely.
For GitLab EE we would have a separate "Upgrading Enterprise Edition from source" guide, which just starts with saying something like "Start by reading the Community Edition instructions", followed by EE specific steps. This way we don't need to duplicate the entire document for EE, or add EE specific bits to the CE document (which would cause conflicts).
For a developer, this means the workflow is as follows:
- Make your changes
- Update
doc/update/update_ce.md
- Create your MR
If your MR is EE specific you would update doc/update/update_ee.md
instead. If your MR contains both CE and EE changes, you'd update both.
For a release manager this means the entire "Step 2: Create the "Update" guides" section and the associated work is no longer necessary, making it much easier to produce the first RC.
@marin @rspeicher @axil @marcia Any thoughts on this proposal?