eloquence
commented
4 years ago One alternative that we discussed briefly was to maintain a stable tag. The process for pushing docs applicable to the latest release could be:
- merge docs change into
developas usual - backport into the latest release branch
- forward the (unsigned)
stabletag.
The current release branch would then always have two tags:
- the signed tag which was used to build the packages, which is SemVer-versioned
- the unsigned tag that represents the
stablebuild of the docs.
Advantages of this approach:
- No mucking around with PRs into another branch, branch deletion, or force pushes
- Reduced potential for confusing branch inconsistencies
- Easier to reason about state
Disadvantages as I understand them:
- Tag pushes are more difficult to audit; a tag theoretically could be applied to
developby accident, pulling in lots of commits that aren't applicable to the current release version - Untested (I've done some preliminary testing of the
stablebranch behavior, but not the tag behavior yet)
Ultimately I don't personally have a strong preference here, either approach seems much more manageable than manual merges or rebases.
For the last two releases, we've experimented with using our historical
masterbranch to build the docs, motivated by avoiding links to outdated docs (#5081) and the fact that we have to merge docs changes after the release tag is signed.This has been a mixed success. We have resolved #5081, but the branch merge tends to require significant manual conflict resolution, and the git log on
masteris no longer an accurate reflection of the commit history.We've agreed to build the branch from a new name (#5321) that is more descriptive. As part of that change, we should also finalize the procedure for updating the branch after each release.
During standup on 6/18, there was broad support for a strategy based on force pushing the branch into the state of the release branch, as part of the release cycle. The exact steps will need to be clearly documented to minimize room for error.