Git Workflow

Development

(Rev. 2026-10-15)

1. Create an issue. (It may be appropriate to create a discussion first.)

• The name of the issue should be a short imperative statement --- e.g., "Allow standard work week to float."

2. Assuming that you will develop the code for this issue ---

• Assign it to yourself.
• Click on the link or button in the issue to create a new (feature) branch. GitHub will create a new tracking branch whose name begins with the issue number and continues with a copy of the issue's title. If possible and reasonable, keep that name.
• Mark your issue as "in progress."

3. On your machine (locally), switch to the new branch. E.g., if the branch is called 123-allow-standard-work-week-to-float, in your terminal, in the top-level repo directory, enter git fetch and then git switch 123-allow-standard-work-week-to-float. (Tab completion should work.)
4. Make your changes in your local branch.

• Write brief commit messages that are imperative statements capturing the most important essential change in conceptual terms --- e.g., Compute workers' busyness on every time step.
• Before you push changes, make sure that you can build and run the executable successfully. Also run the unit tests and make sure that they pass.

5. When your code is ready for review, create a pull request (PR) from the issue (feature) branch on GitHub.

• In the PR description, include the line, Resolves #XXX, where XXX is the number of the original issue (123 in the above example).
• Also in the description, explain your changes at a high level.
• Choose a reviewer from whom to get a review.

7. When the reviewer submits comments, please respond to all comments. Do not mark anything as "resolved."

• The reviewer should then read the responses and mark the conversations as "resolved" when they are indeed resolved.

8. When the reviewer has approved the PR, merge it into main on GitHub. (The author of the code is the one to merge it into main, not the reviewer.)
9. When the code has been merged into main, delete the feature branch on GitHub and the local copy on your machine.

Code Review

When reviewing, please bear in mind the following:

• The logic must be clear. Ask questions if it is not.
• Wherever possible, code should not rely on comments for clarity. Code should be self-explanatory. We should avoid comments as much as possible. (It is OK to use a judiciously-placed comment to refer to documentation about an otherwise complex algorithm, or to warn future developers, e.g., about dependencies in a sequence of events.) The idea is to put the burden of clarity on naming and logic.
• The logic must be sound.
• We must avoid code duplication.
• Functions should be short. A function should do one thing (though it may have some limited side effects).
• Code should be reasonably efficient.
• Code should follow our style guidelines — capitalization, spacing, etc.
• In a class definition, put the public API functions first, starting with the constructors. In the private section, put all functions above the data members.
• In implementation files, function implementations should follow the same order as their corresponding declarations in class (class or struct) definitions.
• The structure of the code base should maintain good separation of concerns.