docs: adjust PR template, finish combining READMEs

adding makefile with example ENV vars to work alongside example config values

Closes #344

CONTRIBUTING.md

@@ -33,6 +33,7 @@ When submitting a PR:
 - Ensure your changes do not reduce code coverage of the test suite.
 - Please do not include merge commits in pull requests; include only commits
   with the new relevant code.
+- PR naming conventions - begins with type (fix, feature, doc, chore, etc) and a short description with no period.
 
 See the main [README.md](/README.md) for information on prerequisites,
 installing, running and testing.

Makefile

@@ -0,0 +1,2 @@
+run-local:
+	RUST_LOG=debug RUST_BACKTRACE=1 cargo run -- --config config/local.toml

PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,11 @@
-Please remember to consult our [contributing guidelines](https://github.com/mozilla-services/syncstorage-rs/blob/master/CONTRIBUTING.md#sending-pull-requests) before opening your PR.
+# Description
 
-- [ ] **Title** begins with _type_ (fix, feature, doc, chore, etc) and a short description with no period
-- [ ] **Description**  outlines the change
-- [ ] **Test cases** included in the change (if appropriate)
-- [ ] **Closes** or **Issue** link to associated issue(s)
+Describe these changes.
+
+# Testing
+
+How should reviewers test?
+
+# Issue(s)
+
+Closes [link](link).

README.md

@@ -5,7 +5,6 @@
 - [Syncstorage-rs](#syncstorage-rs)
   - [System Requirements](#system-requirements)
   - [Local Setup](#local-setup)
-    - [Local DB Setup](#local-db-setup)
     - [MySQL](#mysql)
     - [Spanner](#spanner)
   - [Logging](#logging)
@@ -25,19 +24,19 @@ Mozilla Sync Storage built with [Rust](https://rust-lang.org).
 
 ## System Requirements
 
-* [Rust stable](https://rustup.rs)
-* MySQL 5.7 (or compatible)
-  -* libmysqlclient (`brew install mysql` on macOS, `apt-get install libmysqlclient-dev` on Ubuntu)
-* [Go](https://golang.org/doc/install)
+- [Rust stable](https://rustup.rs)
+- MySQL 5.7 (or compatible)
+  -\* libmysqlclient (`brew install mysql` on macOS, `apt-get install libmysqlclient-dev` on Ubuntu)
+- [Go](https://golang.org/doc/install)
 
 Depending on your OS, you may also need to install `libgrpcdev`, and `protobuf-compiler-grpc`.
 
 ## Local Setup
 
-1. Follow the instructions below to use either MySQL or Spanner. as your DB.
+1. Follow the instructions below to use either MySQL or Spanner as your DB.
 2. Now `cp config/local.example.toml config/local.toml`. Open `config/local.toml` and make sure you have the desired settings configured. For a complete list of available configuration options, check out [docs/config.md](docs/config.md).
-3. `cargo run` - visit `http://localhost:8000/__heartbeat__` to ensure the server is running.
-
+3. `make run-local` starts the server in debug mode, using your new `local.toml` file for config options. Or, simply `cargo run` with your own config options provided as env vars.
+4. Visit `http://localhost:8000/__heartbeat__` to make sure the server is running.
 
 ### MySQL
 
@@ -56,35 +55,38 @@ To setup a fresh MySQL DB and user: (`mysql -u root`):
 
 ### Spanner
 
-Spanner requires a key in order to access the database. It's important that you know which keys have access to the spanner database. Contact your administrator 
-to find out. One you know the key, log into the [Google Cloud Console Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) page. Be sure to 
+Spanner requires a key in order to access the database. It's important that you know which keys have access to the spanner database. Contact your administrator
+to find out. One you know the key, log into the [Google Cloud Console Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) page. Be sure to
 select the correct project.
 
-* Locate the email identifier of the access key and pick the vertical dot menu at the far right of the row. 
-* Select "*Create Key*" from the pop-up menu.
-* Select "JSON" from the Dialog Box.
+- Locate the email identifier of the access key and pick the vertical dot menu at the far right of the row.
+- Select "_Create Key_" from the pop-up menu.
+- Select "JSON" from the Dialog Box.
 
-A proper Key file will be downloaded to your local directory. It's important to safeguard that key file. For this example, we're going to name the file 
+A proper Key file will be downloaded to your local directory. It's important to safeguard that key file. For this example, we're going to name the file
 `sync-spanner.json` and store it in a subdirectory called `./keys`
 
 The proper key file is in JSON format. An example file is provided below, with private information replaced by "`...`"
+
 ```json
-{ 
-    "type": "service_account",
-    "project_id": "...",
-    "private_key_id": "...",
-    "private_key": "...",
-    "client_email": "...",
-    "client_id": "...",
-    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
-    "token_uri": "https://oauth2.googleapis.com/token",
-    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
-    "client_x509_cert_url": "..."
+{
+  "type": "service_account",
+  "project_id": "...",
+  "private_key_id": "...",
+  "private_key": "...",
+  "client_email": "...",
+  "client_id": "...",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "..."
 }
 ```
+
 You can then specify the path to the key file using the environment variable `GOOGLE_APPLICATION_CREDENTIALS` when running the application.
 
 e.g.
+
 ```bash
 RUST_LOG=warn GOOGLE_APPLICATION_CREDENTIALS=`pwd`/keys/sync-spanner.json` cargo run -- --config sync.ini
 ```
@@ -94,7 +96,7 @@ Note, that unlike MySQL, there is no automatic migrations facility. Currently Sp
 ## Logging
 
 - If you want to connect to the existing [Sentry project](https://sentry.prod.mozaws.net/operations/syncstorage-dev/) for local development, login to Sentry, and go to the page with [api keys](https://sentry.prod.mozaws.net/settings/operations/syncstorage-dev/keys/). Copy the `DSN` value, and `export SENTRY_DSN=DSN_VALUE_GOES_HERE` to the environment when running this project.
-- Using envlog: set the `RUST_LOG` env var.
+- Using [env_logger](https://crates.io/crates/env_logger): set the `RUST_LOG` env var.
 
 ## Tests
 
@@ -109,7 +111,6 @@ RUST_TEST_THREADS=1 && /
 cargo test
 ```
 
-
 ### End-to-End tests
 
 Functional tests live in [server-syncstorage](https://github.com/mozilla-services/server-syncstorage/) and can be run against a local server, e.g.:
@@ -128,7 +129,7 @@ Functional tests live in [server-syncstorage](https://github.com/mozilla-service
 
          $ ./local/bin/python syncstorage/tests/functional/test_storage.py http://localhost:8000#<SOMESECRET>
 
-5. Individual tests can be specified via the `SYNC_TEST_PREFIX` env var:
+5.  Individual tests can be specified via the `SYNC_TEST_PREFIX` env var:
 
         $ SYNC_TEST_PREFIX=test_get_collection \
             ./local/bin/python syncstorage/tests/functional/test_storage.py http://localhost:8000#<SOMESECRET>
@@ -137,13 +138,11 @@ Functional tests live in [server-syncstorage](https://github.com/mozilla-service
 
 - `rm Cargo.lock; cargo clean;` - Try this if you're having problems compiling.
 
-
 ## Related Documentation
 
-* [API docs](https://mozilla-services.readthedocs.io/en/latest/storage/apis-1.5.html)
-
-* [Code](https://mozilla-services.github.io/syncstorage-rs/syncstorage/)
+- [API docs](https://mozilla-services.readthedocs.io/en/latest/storage/apis-1.5.html)
 
+- [Code docs](https://mozilla-services.github.io/syncstorage-rs/syncstorage/)
 
 [mpl-svg]: https://img.shields.io/badge/License-MPL%202.0-blue.svg
 [mpl]: https://opensource.org/licenses/MPL-2.0

config/local.example.toml

@@ -1,6 +1,2 @@
-PORT=8000
-RUST_BACKTRACE=1
-RUST_LOG="debug"
-SENTRY_DSN="see readme for instructions"
-SYNC_DATABASE_URL="mysql://sample_user:sample_password@localhost/syncstorage_rs"
-SYNC_MASTER_SECRET="your secret here"
+database_url = "mysql://sample_user:sample_password@localhost/syncstorage_rs"
+master_secret = "some_secret_here"