Git Workflow

We are going to experiment with a single branch that everyone pushes to, rather than multiple feature branches, at least for the next few months while there are a lot of major refactorings and code changes going on. To make this work, we need to be disciplined about how we approach code changes.

Before you commit

The first line of commit messages should be of the form [project-name] one line description of change. If it is a code cleanup commit, then the project name is cleanup.

Before you push

Every time you push to dev, the code MUST compile and you MUST NOT break existing functionality.

If you need to push code that does not meet that standard, you can create a branch, but these should be short lived -- you should plan your changes so that you can push to dev regularly. Strategies include:

• Change a type signature and all uses BEFORE changing a function body.
• When you add a case to a datatype, add all the new cases to the pattern matches with failwith("unimplemented") before implementing them.
• Add "feature flags" (boolean conditionals or conditional compilation flags) for when you're replacing existing functionality until the new version is completely finished.
• Comment out code that doesn't work (only if the other strategies aren't suitable).

When touching definitions that have many clients, talk to the people maintaining or working on that code so that they are aware of, and can provide feedback on, your change.

Before your first push

For first-time contributors, we're going to ask you to make your changes in your own branch. One of the core contributors will help you with regular code review until the code is ready to be pushed to dev. That event also signifies that we are comfortable with you continuing your work in dev following the guidelines above -- congratulations! We will also of course continue to help you with your project after that point. You can always do a pull request rather than directly commit to dev if you are unsure whether you have met the standard above.