Merge pull request #169 from yuvipanda/best-practices

Add best practices recommendation documentation

Author: consideRatio

docs/index.rst

@@ -92,4 +92,5 @@ Full Contents
    contributing
    topic/automatic-merging
    topic/url-options
+   topic/repo-best-practices
    link

docs/topic/repo-best-practices.md

@@ -0,0 +1,41 @@
+# Content git repository best practices
+
+Sometimes, git's flexibility can lead to repositories that cause issues
+when used with nbgitpuller. Here are some recommendations to make your
+nbgitpuller experience smoother.
+
+
+## Never force push
+
+Never use `--force` or `--force-with-lease` when pushing to your repositories.
+This is general good git practice, and unless you have [fairly deep
+understanding](https://xkcd.com/1597/) of how git works, it might screw up some
+of your users' local repositories beyond repair.
+
+If you are using GitHub, you should enable [protected branches](https://docs.github.com/en/github/administering-a-repository/about-protected-branches)
+to prevent accidental force pushes.
+
+## Prevent your repos from becoming huge
+
+Larger git repos increase chances of timeouts and other intermittent failures
+that will be difficult to debug. They might leave your git repo in strange states
+too - contents fetched but not checked out, half-fetched, etc. Try and keep it small -
+under 100MB is great, under 1G is ok, but anything more is probably asking for trouble.
+
+Large datasets are the biggest reason for increasing repository sizes. Try distribute
+datasets some other way, use a subset of data, or compress your data if you need to.
+
+## Don't add `.ipynb_checkpoints` (and similar files) to your git repo
+
+Jupyter uses a hidden `.ipynb_checkpoints` directory to temporarily autosave copies of the
+notebook. If you accidentally commit your local computer's copy of this to the git repo,
+it can cause hard to debug issues when students click nbgitpuller links. The students'
+Jupyter Notebook servers in the JupyterHub will also generate `.ipynb_checkpoints` for
+autosaving, and conflicts between these two can cause issues. Similar issues can happen
+with other temporary, hidden files - like `.DS_Store`, `__pycache__`, etc.
+
+Adding `.ipynb_checkpoints` to your repo's `.gitignore` file will eliminate this
+class of issues completely. `git add` and similar commands will no longer
+accidentally include them in your repo. You can download this [python specific
+gitignore](https://github.com/github/gitignore/blob/master/Python.gitignore)
+file and put it in your repo as `.gitignore`, and it should take care of this.