# GitHub Best Practices

The following are a list of suggested practices for collaborative coding through Git + GitHub.

1. **Put all code in [branches](https://www.atlassian.com/git/tutorials/using-branches#:~:text=In%20Git%2C%20branches%20are%20a,branch%20to%20encapsulate%20your%20changes.).** Branches are a non-destructive, "it doesn't really matter what you do in here," "completely isolated from everyone else's code" way to contribute changes to a project. Once your code on a branch "works," we can consider merging into `main` (formerly `master`) via pull requests as described in the next step.

2. **Open [pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) to merge code into `main`.** Ultimately, we want our "Definitely Works + Has Been Reviewed/Approved By Others + Can Be Considered Correct and Basically Forgotten About" code in the `main` branch. The pull request (PR) feature is an interface on which to collaboratively review, discuss, and iterate on code *changes* (w.r.t. the branch into which you're merging, often `main`). These changes are colloquially referred to as the "diff." On GitHub, this "diff" appears in nice green (for code you've added) and red (for code you've deleted) lines.


3. **Keep pull requests relatively small.** <= ~100 lines of "diff" is ideal. In simple terms, the smaller the diff, the easier it is to review.

4. **Always request a "reviewer" for your code.** While this "locally" slows us down, it often "globally" speeds us up, by reducing the number of bugs that a "fresh set of eyes" can help to catch.


5. **Clear the "output" from all Jupyter notebooks before opening a PR.** This output "clogs" the diff (making it harder to reviewer); furthermore, one should be able to be determinstically reproduce this output by simply running the notebook itself.

6. **Broadly, only keep code in the repo that should be reviewed by others.** In this vein, items like `.DS_Store`, `__pycache__`, etc. should be removed. *The simplest way to programmatically remove these files is by maintaining a .gitignore.* So, to remove all e.g. `.csv` files, we would simply add `**/*.csv` to .gitignore (which removes all `.csv` files in our directory structure).