Expand README (#10)

Author: lwasser

.gitignore

@@ -160,3 +160,5 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+# MAC
+.DS_Store

README.md

@@ -1,7 +1,7 @@
 # devstats
 
-This repository holds the devstats package. devstats uses the github API to
-generate developer statistics and a developer statistics report on a specified
+This repository holds the `devstats` package. `devstats` is a Python command line tool that uses the GitHub GraphQL API to
+generate developer statistics and a developer statistics report for a specified
 project.
 
 ## OAuth key for accessing GitHub
@@ -12,23 +12,43 @@ you need a personal access token with `public_repo` permission to access the Gra
 This code expects the personal access token to be in the environment variable
 `GRAPH_API_KEY`.
 
-You can [create a personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) on GitHub and save it somewhere you trust.
-Then, when you want to use the code: `export GRAPH_API_KEY=<yourkey>`
+You can [create a personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) on GitHub. Save the token in a trusted location.
+
+Finally, add the token to your environment using:
+
+`export GRAPH_API_KEY=<yourkey>`
 
 ## Query script
 
 The `query.py` script can be used to collect data for other projects like
-so: `python query.py <repo_owner> <repo_name>` where `repo_owner` and
+so: `devstats query.py <repo_owner> <repo_name>` where `repo_owner` and
 `repo_name` are the names of the **org** and **repo** on GitHub, respectively.
 
-First you need to install the required Python packages:
+To download the latest data for `pandas` use the following command:
 
 ```bash
-pip install -r requirements.txt
+devstats query.py pandas-dev pandas
 ```
 
-For example, to download the latest data for `pandas`:
+The command will collect information from GitHub and generate two output files in the same directory where you ran it as follows:
 
-```bash
-python query.py pandas-dev pandas
-```
+`packagename_issues.json`: this file contains information about issues for the repository of interest.
+`packagename_PRs.json`: this file contains information associated with pull requests for the repository of interest.
+
+## Development instructions
+
+If you wish to contribute to devstats:
+
+1. Fork and clone the repository
+2. Create a new branch with your proposed feature or change to the package repository
+
+### Code Style / Pre-commit
+
+We use `pre-commit` to ensure the code style is consistent. To install pre-commit locally:
+
+1. First install pre-commit: `pip install pre-commit`
+2. Install all of the pre-commit hooks by running `pre-commit install`
+
+Once you have `pre-commit` installed, the code stylers and linters
+defined in the `pre-commit-config.yaml` will run each time you
+commit modified changes to git locally.