Skip to content

Haddock workflow needs improvement (git-subtree)

Problem

There appears to be no good workflow for contributing patches that change both GHC and Haddock.

For contributors who have push access to both repositories, it is at least tolerable:

  1. create a Haddock branch with the required changes
  2. create a GHC branch with the required changes
  3. wait for the GHC change to get merged to master
  4. fast-forward the Haddock change to the ghc-head branch; in case a fast-forward is impossible, cherry-pick the commit to ghc-head and push another commit to GHC master to update the Haddock submodule

Roundabout, but possible.

For contributors who do not have push access to both repositories, each step is much harder, as working with forks implies messing with .gitmodules, which arguably should stay constant.

Proposed solution

  1. on GitLab we have a full copy of haddock (via git subtree) inside GHC's repository, the development is done there.
  2. on GitHub we no longer have the ghc-head branch, but contributors can create PRs against ghc-8.6 or whatever is the latest release
  3. once per release, we do a git subtree push to create a new release branch on the GitHub's repo
  4. in GHC, when backporting commits to minor releases, we do git subtree pull to get the relevant haddock changes

This means that the main workflow doesn't even require dealing with git subtree, it's only backporting/release when it matters. The rest of the time one can pretend that haddock lives in the GHC's repo.

Note: none of the above applies to the Cabal submodule. Cabal isn't tied to a particular GHC version, so whatever changes are made there should work both before and after corresponding GHC commits. It means that one can do Cabal's changes first, GHC's second, no atomicity required.

Edited by Vladislav Zavialov
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information