-
Notifications
You must be signed in to change notification settings - Fork 35
GitBestPractices
Ethan Coon edited this page Jul 25, 2023
·
2 revisions
ATS is moving toward a more formal model of "squash and rebase". This model will result in a cleaner history, simpler debugging, and a master branch that "always passes tests".
To contribute any change to the code, please follow the following best practices:
- Do all development on a branch.
git branch -b YOU/branch_name - Name your branches
YOU/branch_name, e.g.ecoon/bugfix_64(addresses issue 64), orecoon/new_widget_evaluator - If you will change Amanzi or add a regression test or demo, make a branch on those repositories of the same name. The same name ensures CI can do the right thing when testing.
- Make an issue to describe your development goal. Solicit feedback on that issue if you would like help or advice.
- If the problem is a bug, add or modify an existing test to show the buggy behavior. If it is a new feature, add a new test that will use the new feature (see ats-regression-tests ).
- Commit and push early and often to your branch. It is OK if intermediate commits do not pass tests!
- Do not merge from master or other branches into your branch. Instead, rebase your branch onto master or that branch (see below).
- Run the tests on your local machine to confirm that they pass.
- Create a pull request, linking to your issue to describe what is being done. If you think the pull request isn't quite done but needs some feedback, put "WIP" for "Work in Progress" at the start of the title. Make the pull request from your branch to master.
- Confirm that tests pass in the CI
- Request a review from another developer. Iterate with that reviewer to get the code cleaned up and ready to go.
- Run clang-format
All pull requests should be merged via "Squash and Rebase". This ensures that all commits on master pass tests. If there is a conflict, the developer should manually squash and rebase. The easiest way to do this is:
- Squash your commits:
git rebase --keep-base -i master. This is an interactive rebase, so it will open the rebase in a text editor, where you will want to squash all but the first commit. Assorted ways to do this are described here. - Rebase onto master (or another branch):
git rebase master. - Upon rebasing, you'll have to force your push, because you have changed the history of your branch:
git push -f - Now you can re-ask the maintainer to accept your PR.
During either rebase, you may have to fix conflicts. Conflicts here will be places where the developer and master have both changed lines of code. Mergetools can help a lot here.