Refactor/update-contributing-guide

.github/CONTRIBUTING.md

@@ -1,121 +1,120 @@
 # Contributing Guide
 
-* Check the [GitHub Issues](https://github.com/burnash/gspread/issues) for open issues that need attention.
-* Follow the [How to submit a contribution](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution) Guide.
+- Check the [GitHub Issues](https://github.com/burnash/gspread/issues) for open issues that need attention.
+- Follow the [How to submit a contribution](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution) Guide.
 
-* Make sure unit tests pass. Please read how to run unit tests below.
+- Make sure unit tests pass. Please read how to run unit tests [below](#run-tests-offline).
 
-* If you are fixing a bug:
-  * If you are resolving an existing issue, reference the issue id in a commit message `(fixed #XXX)`.
-  * If the issue has not been reported, please add a detailed description of the bug in the PR.
-  * Please add a regression test case.
+- If you are fixing a bug:
+  - If you are resolving an existing issue, reference the issue ID in a commit message `(e.g., fixed #XXXX)`.
+  - If the issue has not been reported, please add a detailed description of the bug in the Pull Request (PR).
+  - Please add a regression test case to check the bug is fixed.
 
-* If you are adding a new feature:
-  * Please open a suggestion issue first.
-  * Provide a convincing reason to add this feature and have it greenlighted before working on it.
-  * Add tests to cover the functionality.
+- If you are adding a new feature:
+  - Please open a suggestion issue first.
+  - Provide a convincing reason to add this feature and have it greenlighted before working on it.
+  - Add tests to cover the functionality.
 
-* Please follow [Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/).
+- Please follow [Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/).
 
-## Testing
+## CI checks
 
-1. [Obtain OAuth2 credentials from Google Developers Console](http://gspread.readthedocs.org/en/latest/oauth2.html)
+If the [test](#run-tests-offline) or [lint](#lint) commands fail, the CI will fail, and you won't be able to merge your changes into gspread.
 
-2. Run tests offline:
+Use [format](#format) to format your code before submitting a PR. Not doing so may cause [lint](#lint) to fail.
 
-Run the test suite using your current python version, in offline mode.
-This will use the curently recorded HTTP requests + responses. It does not make any HTTP call, does not require an active internet connection.
+## Install dependencies
 
-**Note:** the CI runs that command, if it fail you won't be able to merge
-your changes in GSpread.
+Installing all the `*.txt` files is optional (tox installs dependencies per-run).
 
-```
-tox -e py
+```bash
+pip install tox
+pip install -r ./test-requirements.txt -r ./lint-requirements.txt -r ./docs/requirements.txt
 ```
 
-**Tip:** To run a specific test method use the option `-k` to specifcy a test name and `-v` and `-s` to get test's output on console.
+## Run tests (offline)
 
-Example:
+If the calls to the Sheets API have not changed, you can run the tests offline. Otherwise, you will have to [run them online](#run-tests-online) to record the new API calls.
 
-```
-tox -e py -- -k test_find -v -s
+This will use the currently recorded HTTP requests + responses. It does not make any HTTP calls, and does not require an active internet connection.
+
+```bash
+tox -e py
 ```
 
-**Note:** gspread uses [vcrpy](https://github.com/kevin1024/vcrpy) to record and replay HTTP interactions with Sheets API.
+### Run a specific test
 
-You must in that case provide a service account credentials in order to make the real HTTP requests, using `GS_CREDS_FILENAME` environment variable.
+```bash
+tox -e py -- -k TEST_NAME -v -s
+```
 
-You can control vcrpy's [Record Mode](https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes) using `GS_RECORD_MODE` environment variable.
+## Format
 
-The following command will run the entire test suite and record every HTTP request.
-```
-GS_RECORD_MODE=all GS_CREDS_FILENAME=<YOUR_CREDS.json> tox -e py
+```bash
+tox -e format
 ```
 
-You need to update the recorded HTTP requests in the following cases:
+## Lint
 
-- new test is added
-- a existing test is updated and does a new HTTP request
-- gspread is updated and does a new HTTP request
+```bash
+tox -e lint
+```
 
-In any of the above cases:
+## Render Documentation
 
-- remove the file holding the init/teardown of the test suite.
+The documentation uses [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index) markup and is rendered by [Sphinx](http://www.sphinx-doc.org/).
 
-  ex: for the file `tests/cell_test.py` delete `tests/cassettes/CellTest.json`
-- please update the HTTP recording using the command above
-- set the `GS_RECORD_MODE` to `new_episodes`.
+```bash
+tox -e doc
+```
 
-This will tell `vcrpy` to record only new episodes and replay existing episodes.
+The rendered documentation is placed into `docs/build/html`. `index.html` is an entry point.
 
-**Note:** this will mostly result in a lot of udpated files under `tests/cassettes/` don't forget to add them in your PR.
+## Run tests (online)
 
-Add these new files a dedicated commit, in order to make the review process easier please.
+gspread uses [vcrpy](https://github.com/kevin1024/vcrpy) to record and replay HTTP interactions with Sheets API.
 
-The following command will replay existing requests and record new requests:
-```
-GS_RECORD_MODE=new_episodes GS_CREDS_FILENAME=<YOUR_CREDS.json> tox -e py
-```
+### `GS_CREDS_FILENAME` environment variable
 
-Then run the tests in offline mode to make sure you have recorded everything.
+You must provide service account credentials using the `GS_CREDS_FILENAME` environment variable in order to make HTTP requests to the Sheets API.
 
-```
-tox -e py
-```
+[Obtain OAuth2 credentials from Google Developers Console](http://gspread.readthedocs.org/en/latest/oauth2.html).
 
-**Note::** In some cases if the test suite can't record new episodes or it can't
-replay them offline, you can run a complete update of the cassettes using the following command:
+### `GS_RECORD_MODE` environment variable
 
-```
-GS_RECORD_MODE=all GS_CREDS_FILENAME=<YOUR_CREDS.json> tox -e py
-```
+You can control vcrpy's [Record Mode](https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes) using `GS_RECORD_MODE` environment variable. It can be:
 
-3. Format your code:
+- `all` - record all HTTP requests, overwriting existing ones
+- `new_episodes` - record new HTTP requests and replay existing ones
+- `none` - replay existing HTTP requests only
 
-Use the following command to format your code. Doing so will ensure
-all code respects the same format.
+In the following cases, you must record new HTTP requests:
 
-```
-tox -e format
-```
+- a new test is added
+- an existing test is updated and does a new HTTP request
+- gspread is updated and does a new HTTP request
 
-Then run the linter to validate change, if any.
+### Run test, capturing *all* HTTP requests
 
-**Note:** the CI runs that command, if it fail you won't be able to merge
-your changes in GSpread.
+In some cases if the test suite can't record new episodes, or it can't replay them offline, you can run a complete update of the cassettes.
 
-```
-tox -e lint
+```bash
+GS_CREDS_FILENAME=<./YOUR_CREDS.json> GS_RECORD_MODE=all tox -e py
 ```
 
-## Render Documentation
+### Run test, capturing *only new* HTTP requests
 
-The documentation uses [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index) markup and is rendered by [Sphinx](http://www.sphinx-doc.org/).
+To record new HTTP requests:
 
-To build the documentation locally, use the following command:
+1. Remove the file holding the recorded HTTP requests of the test(s).
+  (e.g.: for the file `tests/cell_test.py` delete `tests/cassettes/CellTest.json`)
+1. Run the tests with `GS_RECORD_MODE=new_episodes`.
 
+```bash
+GS_CREDS_FILENAME=<./YOUR_CREDS.json> GS_RECORD_MODE=new_episodes tox -e py
 ```
-tox -e doc
-```
 
-Once finished, the rendered documentation will be in `docs/build/html` folder. `index.html` is an entry point.
+This will mostly result in a lot of updated files in `tests/cassettes/`. Don't forget to add them in your PR.
+Please add them in a dedicated commit, in order to make the review process easier.
+
+Afterwards, remember to [run the tests in offline mode](#run-tests-offline) to make sure you have recorded everything correctly.

.gitignore

@@ -11,3 +11,6 @@ env/
 # tox testrunner support
 .tox/
 gspread.egg-info/
+
+# vscode
+.vscode/

README.md

@@ -176,16 +176,16 @@ worksheet.batch_update([{
 
 ## [Documentation](https://gspread.readthedocs.io/en/latest/)
 
+### Ask Questions
+
+The best way to get an answer to a question is to ask on [Stack Overflow with a gspread tag](http://stackoverflow.com/questions/tagged/gspread?sort=votes&pageSize=50).
+
 ## [Contributors](https://github.com/burnash/gspread/graphs/contributors)
 
 ## How to Contribute
 
 Please make sure to take a moment and read the [Code of Conduct](https://github.com/burnash/gspread/blob/master/.github/CODE_OF_CONDUCT.md).
 
-### Ask Questions
-
-The best way to get an answer to a question is to ask on [Stack Overflow with a gspread tag](http://stackoverflow.com/questions/tagged/gspread?sort=votes&pageSize=50).
-
 ### Report Issues
 
 Please report bugs and suggest features via the [GitHub Issues](https://github.com/burnash/gspread/issues).