Merge pull request #391 from pcattori/contributor-guide

Simplify contributor docs
Datatamer · Jun 25, 2020 · 50b459a · 50b459a
2 parents 80dac5d + 2886ff9
commit 50b459a
Show file tree

Hide file tree

Showing 13 changed files with 61 additions and 109 deletions.
diff --git a/docs/contributor-guide.md b/docs/contributor-guide.md
@@ -1,11 +1,23 @@
 # Contributor guide
 
-  * [Bug Reports and Feature Requests](contributor-guide/bugs-and-features)
-  * [Code Migrations](contributor-guide/migration)
-  * [Configure your Text Editor](contributor-guide/config-text-editor)
-  * [Install](contributor-guide/install)
-  * [Navigating Inheritance](contributor-guide/navigating-inheritance)
-  * [Pull Requests](contributor-guide/pull-request)
-  * [Run and Build](contributor-guide/run-and-build)
-  * [Style Guide](contributor-guide/style-guide)
-  * [Toolchain](contributor-guide/toolchain)
+Make sure you are viewing the [latest version of Contributor Guide](https://tamr-client.readthedocs.io/en/latest/contributor-guide.html).
+
+## Contributing feedback
+
+Check through existing issues (open and closed) to confirm that the bug or feature hasn’t been reported before.
+
+If the bug/feature has been submitted already, leave a like 👍 on the description of the Github Issue.
+
+### Bug reports
+Submit bug reports as [Github issues](https://github.com/Datatamer/tamr-client/issues/new/choose).
+
+### Feature requests
+Submit feature requests as [Github issues](https://github.com/Datatamer/tamr-client/issues/new/choose).
+
+
+## Contributing code
+* [Install the codebase](contributor-guide/install)
+* [Run dev tasks](contributor-guide/dev-tasks)
+* [Configure your text editor](contributor-guide/text-editor)
+* [Read the style guide](contributor-guide/style-guide)
+* [Submit a pull request](contributor-guide/pull-request)
diff --git a/docs/contributor-guide/bugs-and-features.md b/docs/contributor-guide/bugs-and-features.md
diff --git a/docs/contributor-guide/config-text-editor.md b/docs/contributor-guide/config-text-editor.md
diff --git a/docs/contributor-guide/run-and-build.md → docs/contributor-guide/dev-tasks.md b/docs/contributor-guide/run-and-build.md → docs/contributor-guide/dev-tasks.md
@@ -1,4 +1,4 @@
-# Run and Build
+# Run dev tasks
 
 This project uses [nox](https://nox.thea.codes/en/stable/).
 
@@ -15,7 +15,7 @@ prn # with alias
 poetry run nox # without alias
 ```
 
-## Linting & Formatting
+## Linting
 
 To run linter:
 
@@ -24,6 +24,8 @@ prn -s lint # with alias
 poetry run nox -s lint # without alias
 ```
 
+## Formatting
+
 To run formatter:
 
 ```sh

diff --git a/docs/contributor-guide/install.md b/docs/contributor-guide/install.md
@@ -1,9 +1,12 @@
-# Install
+# Installation
 
-This project uses `pyenv` and `poetry`.
-If you do not have these installed, checkout the [toolchain guide](toolchain).
+### Pre-requisites
 
----
+1. Install [build dependencies for pyenv](https://github.com/pyenv/pyenv/wiki#suggested-build-environment)
+2. Install [pyenv](https://github.com/pyenv/pyenv#installation)
+3. Install [poetry](https://python-poetry.org/docs/#installation)
+
+### Clone + install
 
 1. Clone your fork and `cd` into the project:
 
@@ -12,20 +15,16 @@ If you do not have these installed, checkout the [toolchain guide](toolchain).
     cd tamr-client
     ```
 
-2. Set a Python version for this project. Must be Python 3.6+ (e.g. `3.7.3`):
-
-    ```sh
-    pyenv local 3.7.3
-    ```
+2. Install all Python versions in [.python-version](https://github.com/Datatamer/tamr-client/blob/master/.python-version):
 
-3. Check that your Python version matches the version specified in `.python-version`:
+    [Dev tasks](dev-tasks) will use these Python versions.
 
     ```sh
-    cat .python-version
-    python --version
+    # run `pyenv install` for each line in `.python-version`
+    cat .python-version | xargs -L 1 pyenv install
     ```
 
-4. Install dependencies via `poetry`:
+3. Install project dependencies via `poetry`:
 
     ```sh
     poetry install

diff --git a/docs/contributor-guide/migration.md b/docs/contributor-guide/migration.md
diff --git a/docs/contributor-guide/navigating-inheritance.md b/docs/contributor-guide/navigating-inheritance.md
diff --git a/docs/contributor-guide/pull-request.md b/docs/contributor-guide/pull-request.md
@@ -1,16 +1,16 @@
-# ↪️ Pull Requests
+# Contributing pull requests
 
-For larger, new features:
+### ️RFCs
+If the proposed changes require design input, [open a Request For Comment issue](https://github.com/Datatamer/tamr-client/issues/new/choose).
 
-  [Open an RFC issue](https://github.com/Datatamer/tamr-client/issues/new/choose).
-  Discuss the feature with project maintainers to be sure that your change fits with the project vision and that you won't be wasting effort going in the wrong direction.
+Discuss the feature with project maintainers to be sure that your change fits with the project vision and that you won't be wasting effort going in the wrong direction.
 
-  Once you get the green light 🚦 from maintainers, you can proceed with the PR.
+Once you get the green light 🟢 from maintainers, you can proceed with the PR.
 
----
+### Pull requests
 
 Contributions / PRs should follow the
-[Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow):
+[Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow). In short:
 
   1. Fork it: `https://github.com/[your-github-username]/tamr-client/fork`
   2. Create your feature branch:
@@ -33,12 +33,15 @@ Contributions / PRs should follow the
 
   5. Create a new Pull Request
 
-----
+### Commits
 
-We optimize for PR readability, so please squash commits before and during the PR review process if you think it will help reviewers and onlookers navigate your changes.
+Split and squash commits as necessary to create a clean `git` history. Once you ask for review, only add new commits (do not change existing commits) for reviewer convenience. You may change commits in your PR only if reviewers are ok with it.
 
-Don't be afraid to `push -f` on your PRs when it helps our eyes read your code.
+Also, write [good commit messages](https://chris.beams.io/posts/git-commit/)!
 
----
+### CI checks
 
-Remember to check for any [ongoing code migrations](migration) that may be relevant to your PR.
+Continuous integration (CI) checks are run automatically for all pull requests.
+CI runs the same [dev tasks](dev-tasks) that you can run locally.
+
+You should run dev tasks locally _before_ submitting your PR to cut down on subsequent commits to fix the CI checks.
diff --git a/docs/contributor-guide/resource:collectionRequest.png b/docs/contributor-guide/resource:collectionRequest.png
diff --git a/docs/contributor-guide/resource:collectionRoute.png b/docs/contributor-guide/resource:collectionRoute.png
diff --git a/docs/contributor-guide/style-guide.md b/docs/contributor-guide/style-guide.md
@@ -4,7 +4,7 @@
 Code should generally conform to the [PEP8 style guidelines](https://www.python.org/dev/peps/pep-0008/). 
   * [Flake8](https://flake8.pycqa.org/en/latest/) is a linter to help check that code is aligned with these formatting requirements
   * [Black](https://black.readthedocs.io/en/stable/) is a formatter that can be used to automatically reformat code to resolve many (but not all) formatting issues
-  * For details on using these tools [see here](run-and-build)
+  * For details on using these tools, see [the dev tasks guide](dev-tasks)
 
 ### Structure
 * Classes with methods should be avoided in favor of simple [dataclasses](https://docs.python.org/3/library/dataclasses.html) and functions

diff --git a/docs/contributor-guide/text-editor.md b/docs/contributor-guide/text-editor.md
@@ -0,0 +1,8 @@
+# Configure your Text Editor
+
+### Atom
+- [python-black](https://atom.io/packages/python-black)
+- [linter-flake8](https://atom.io/packages/linter-flake8)
+
+### VS Code
+- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
diff --git a/docs/contributor-guide/toolchain.md b/docs/contributor-guide/toolchain.md