Merge pull request #464 from manics/code-repo-standards

Add initial repo and code standards

Author: willingc

docs/index-team_guides.rst

@@ -10,6 +10,7 @@ Guides for JupyterHub teams
 
    team/member-guide
    team/skills
+   team/repository-code-standards
    team/adding-members
    team/shared-infrastructure
    talking

docs/team/repository-code-standards.md

@@ -0,0 +1,37 @@
+# Repository Management and Code Standards
+
+JupyterHub projects should take advantage of pre-commit and tools to help maintain consistent formatting within a repo to improve overall code quality, review efficiency, and readability of code.
+Sensible use of pre-commit to run formatting tools and code linters can add consistency and improve maintainability.
+
+## Preferred tools and pre-commit hooks
+
+The team has found the following tools and their pre-commit hooks to be useful. The following pre-commit hooks can be added to any repo when convenient, though please communicate with anyone who has an open pull request if it will lead to major conflicts:
+
+  - [black](https://black.readthedocs.io/)
+  - [prettier](https://prettier.io/)
+  - [flake8](https://flake8.pycqa.org/en/latest/)
+  - **TODO: standard pre-commit hooks, such as isort, etc. (To be determined and listed here)**
+
+## Applying to repos
+
+When creating a new repo, please use any pre-commit hooks and tools that are useful.
+
+When working with an existing repo, please balance the benefits of adding a tool or pre-commit hook with considerations such as
+  - the amount of code churn
+  - how it will improve code maintainability
+  - the time it may add to CI runs.
+
+## Configuration of a tool
+
+In general using the default settings for tools is preferred, but use your judgment as to whether to apply a stricter or more lenient configuration for linting code.
+Example configurations are in:
+
+  - [JupyterHub](https://github.com/jupyterhub/jupyterhub/) (a large repository which was converted and therefore has a fairly lax configuration)
+  - [nativeauthenticator](https://github.com/jupyterhub/nativeauthenticator) (a fairly strict configuration)
+
+Other linters, autoformatters and tools can be added to other repos on an ad-hoc basis if it's not too disruptive- this is a good way to try out new tools.
+In general, big changes should not be made to high profile repos without prior discussion.
+
+## Proposing organization-wide use of a tool
+
+If the new tool is useful across the organisation please propose it in a new team-compass GitHub issue, outlining the advantages and disadvantages.