Git Workflow

The Hazel codebase is often undergoing multiple concurrent large refactorings. To mitigate the pain of large merge conflicts, we adopt a Git workflow of feature branches combined with frequent merges from and into dev, our central development branch. Frequent synchronization with dev will help keep other contributors up-to-date on your code changes that may overlap or unintentionally interact with theirs (unavoidable given how large each refactoring is) and help minimize wasted effort due to outdated assumptions (e.g. someone writes a ton of code using a datatype that you had refactored but not yet merged into dev).

This system requires some discipline in order to work reasonably. You should aim to synchronize your branch with dev not only frequently, but also such that dev can always build with no regressions in functionality. Your feature does not need to be complete to be merged into dev.

Starting a project

Create a new branch off of dev with your project name all lowercase (Git on Windows/Mac doesn't deal well with uppercase). Push your branch to GitHub and open a pull request from your branch into dev. The pull request provides a convenient place for other contributors to monitor and provide early feedback on your code.

When you get back to work

Pull the latest changes on dev from GitHub and merge them into your branch. Prioritize resolving merge conflicts.

Do not rebase onto dev -- rebasing deletes your existing commits and replaces them with new ones, which screws with any existing feedback on your pull request.

Before you commit to your branch

Make sure you have followed the Code Style Guide.

Any commits into dev should have a tag on the commit message, e.g. [cleanup] created signature file. The tag should either be the branch name for the project that was squashed-and-merged into dev, or one of the following:

• [build] -- build system tweaks
• [cleanup] -- code cleanup tasks

If none of those make sense, ask on Slack and we can possibly add new tags.

After you commit to your branch

Consider whether you could merge your latest changes into dev. If not, prioritize getting your branch into a state suitable for merging into dev.

It's easy to let merges into dev blow up in size in the name of preserving build and functionality. Mitigation strategies include:

• If you discover in the course of implementing your feature that you need to perform a supporting but inessential refactor to some existing datatype or signature
  1. stash your current changes that depend on the refactor
  2. perform the refactor, commit and merge to dev
  3. unstash your changes and proceed
• If you add a new variant to a datatype, first commit and merge to dev a set of changes that adds the variant to all relevant case expressions with failwith("unimplemented") before you being commit any actual implementation.
• If you are aware that your changes may lead to difficult-to-resolve merge conflicts with the changes of another contributor, reach out to that person directly and communicate about how you may better synchronize your work.
• Comment out code that doesn't work (only if the other strategies aren't suitable).