Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise and document docs update procedure #5326

Closed
eloquence opened this issue Jun 18, 2020 · 2 comments
Closed

Revise and document docs update procedure #5326

eloquence opened this issue Jun 18, 2020 · 2 comments

Comments

@eloquence
Copy link
Member

For the last two releases, we've experimented with using our historical master branch 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 master is 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.

@eloquence
Copy link
Member Author

eloquence commented Jun 18, 2020

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 develop as usual
  • backport into the latest release branch
  • forward the (unsigned) stable tag.

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 stable build 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 develop by accident, pulling in lots of commits that aren't applicable to the current release version
  • Untested (I've done some preliminary testing of the stable branch 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.

@eloquence
Copy link
Member Author

This was completed via #5441.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants