docs: Add guides, update READMEs (#9)

* Changes from old repo

* adding screenshot

* tweak to project description

* Simplify dev setup documentation

* resetdb: don't err if db doesn't exist

* Cleanup contributing guidelines a bit

* Update smoketest readme

* add Dockerfile

* getting started guide

* dev setup guide

* add mailgun section

* add note about API-only mode

* attempt to start postgres container on failure (fix dev issue)

* shorten getting started intro

* tweaks to postgres getting started info

* add link to effective Go in CONTRIBUTING.md

* add links to more info for tests

* add go unit test example

* update label query in README

Co-Authored-By: Mitch Cimenski <mitch@m17ch.com>
Co-Authored-By: Arundhati Rao <arao4@buffalo.edu>

CONTRIBUTING.md

@@ -4,13 +4,13 @@ We welcome feature requests, bug reports and contributions for code and document
 
 ## Reporting Issues
 
-Reporting bugs can be done in the GitHub [issue tracker](https://github.com/target/goalert/issues). Please search for a possible pre-existing issue first to help prevent duplicates.
+Reporting bugs can be done in the GitHub [issue tracker](https://github.com/target/goalert/issues). Please search for existing issues first to help prevent duplicates.
 
 Please include the version (`goalert version`) with new bug reports.
 
 ## Code Contribution
 
-GoAlert is already used in production environments, so any new changes/features/functionality must (where possible):
+GoAlert is already used in production environments, so any new changes/features/functionality must, where possible:
 
 - Not alter existing behavior without an explicit config change
 - Co-exist with older versions without disruption
@@ -24,7 +24,7 @@ As an example, things like DB changes/migrations should preserve behavior across
 
 Patches are welcome, but we ask that any significant change start as an [issue](https://github.com/target/goalert/issues/new) in the tracker, prefereably before work is started.
 
-Be sure to run `make check` before opening a PR to catch common errors.
+Be sure to run `make check` and tests before opening a PR to catch common errors.
 
 ### UI Change Guidelines
 
@@ -34,6 +34,6 @@ Be sure to run `make check` before opening a PR to catch common errors.
 
 ### Backend Change Guidelines
 
-- Use unit tests as a tool to validate complex logic
+- Use unit tests as a tool to validate complex logic. For [example](./schedule/rule/weekdayfilter_test.go).
 - New functionality should have a behavioral smoketest at a minimum. For [example](./smoketest/simplenotification_test.go). Documentation on our smoketest framework can be found [here](./smoketest/README.md).
-- New Go code should pass `golint`, exported functions/methods should be commented, etc..
+- Go code should [follow best practices](https://golang.org/doc/effective_go.html), exported functions/methods should be commented, etc..

Makefile

@@ -146,7 +146,7 @@ postgres:
 		-e POSTGRES_USER=goalert \
 		--name goalert-postgres \
 		-p 5432:5432 \
-		postgres:11-alpine
+		postgres:11-alpine || docker start goalert-postgres
 
 regendb: bin/goalert migrate/inline_data_gen.go config.json.bak
 	go run ./devtools/resetdb --with-rand-data

README.md

@@ -1,52 +1,39 @@
 # GoAlert
 
-GoAlert is an on-call alerting platform written in Go.
+GoAlert provides on-call scheduling, automated escalations and notifications (like SMS or voice calls) to automatically engage the right person, the right way, and at the right time.
 
-## All-In-One (demo) Container
+![image](https://user-images.githubusercontent.com/23565500/58896528-c1cdb100-86bb-11e9-96f1-a57198ece062.png)
 
-The quickest way to explore GoAlert is by using the GoAlert [all-in-one container](https://hub.docker.com/r/goalert/all-in-one).
+## Installation
 
-- Ensure you have Docker Desktop installed ([Mac](https://docs.docker.com/docker-for-mac/release-notes/) / [Windows](https://docs.docker.com/docker-for-windows/release-notes/))
-- `docker run -it --rm --name goalert-demo -p 8081:8081 goalert/all-in-one`
+GoAlert is distributed as a single binary with release notes available from the [GitHub Releases](https://github.com/target/goalert/releases) page.
 
-Using a web browser, navigate to `http://localhost:8081` and log in with user `admin` and password `admin123`.
+See our [Getting Started Guide](./docs/getting-started.md) for running GoAlert in a production environment.
 
-## Development
+### Quick Start
 
-Ensure you have docker, Go, node (and yarn), and make installed.
+```bash
+docker run -it --rm -p 8081:8081 goalert/all-in-one
+```
 
-- If you do not have Postgres installed/configured, first run `make postgres`, GoAlert is built and tested against Postgres 11.
-- For the first start, run `make regendb` to migrate and add test data into the DB. This includes an admin user `admin/admin123`.
-- To start GoAlert in development mode run `make start`.
-- To build the GoAlert binary run `make bin/goalert BUNDLE=1`.
+GoAlert will be running at [localhost:8081](http://localhost:8081). You can login with `admin/admin123`.
 
-### Automated Browser Tests
+## Contributing
 
-To run automated browser tests, you can start Cypress in one of the following modes:
+If you'd like to contribute to GoAlert, please see our [Contributing Guidelines](./CONTRIBUTING.md) and the [Development Setup Guide](./docs/development-setup.md).
 
-- `make cy-wide` Widescreen format, in dev mode.
-- `make cy-mobile` Mobile format, in dev mode.
-- `make cy-wide-prod` Widescreen format, production build.
-- `make cy-mobile-prod` Mobile format, production build.
+Please also see our [Code of Conduct](./CODE_OF_CONDUCT.md).
 
-### Running Smoketests
+## Contact Us
 
-A suite of functional/behavioral tests are maintained for the backend code. These test various APIs and behaviors
-of the GoAlert server component.
+If you need help or have a question, the `#goalert` Slack channel is available on [gophers.slack.com](https://gophers.slack.com/messages/goalert/).
 
-Run the full suite with `make smoketest`.
+To access Gophers Slack and the `#goalert` channel, you will need an invitation. You request one through the automated process here: https://invite.slack.golangbridge.org/
 
-### Running Unit Tests
+- Vote on existing [Feature Requests](https://github.com/target/goalert/issues?q=is%3Aopen+label%3Aenhancement+sort%3Areactions-%2B1-desc) or submit [a new one](https://github.com/target/goalert/issues/new)
+- File a [bug report](https://github.com/target/goalert/issues)
+- Report security issues to security@goalert.me
 
-All unit tests can be run with `make test`.
+## License
 
-UI Unit tests are found under the directory of the file being tested, with the same file name, appended with `.test.js`. They can be run independently with `make jest`. Watch mode can be enabled with `make jest JEST_ARGS=--watch`.
-
-### Setup Postgres
-
-By default, the development code expects a postgres server configured on port `5432`, with the user and DB `goalert`.
-
-Alternatively, you can run `make postgres` to configure one in a docker container.
-
-- You can reset the dev database with `make resetdb`
-- You can reset and generate random data with `make regendb`, this includes generating an admin user `admin/admin123`
+GoAlert is licensed under the [Apache License, Version 2.0](./LICENSE.md).

devtools/ci/dockerfiles/goalert/Dockerfile

@@ -0,0 +1,4 @@
+FROM alpine
+RUN apk --no-cache add tzdata ca-certificates
+COPY goalert /usr/bin/
+CMD ["/usr/bin/goalert"]

devtools/resetdb/main.go

@@ -491,7 +491,7 @@ func recreateDB() error {
 	}
 	defer db.Close()
 
-	_, err = db.Exec("drop database goalert")
+	_, err = db.Exec("drop database if exists goalert")
 	if err != nil {
 		return err
 	}

docs/development-setup.md

@@ -0,0 +1,54 @@
+## Development Setup
+
+This guide assumes you have the commands `docker`, `go`, `node`, `yarn`, and `make` installed/available.
+
+## Database (PostgreSQL)
+
+GoAlert is built and tested against Postgres 11. Version 9.6 should still work as of this writing, but is not recomended as future versions may begin using newer features.
+
+The easiest way to setup Postgres for development is to run `make postgres`.
+This will start a docker container with the correct configuration for the dev environment.
+
+### Manual Configuration
+
+If you already have Postgres running locally you can create the `goalert` role.
+
+```sql
+CREATE ROLE goalert WITH LOGIN SUPERUSER;
+```
+
+Currently the dev user must be a superuser to enable `pgcrypto` with `CREATE EXTENSION`.
+
+#### Toolchain Requirements
+
+- For the first start, run `make regendb` to migrate and add test data into the DB. This includes adding an admin user `admin/admin123`.
+- To start GoAlert in development mode run `make start`.
+- To build the GoAlert binary run `make bin/goalert BUNDLE=1`.
+
+### Automated Browser Tests
+
+To run automated browser tests, you can start Cypress in one of the following modes:
+
+- `make cy-wide` Widescreen format, in dev mode.
+- `make cy-mobile` Mobile format, in dev mode.
+- `make cy-wide-prod` Widescreen format, production build.
+- `make cy-mobile-prod` Mobile format, production build.
+
+The Cypress UI should start automatically.
+
+More information about browser tests can be found [here](../web/src/cypress/README.md).
+
+### Running Smoketests
+
+A suite of functional/behavioral tests are maintained for the backend code. These test various APIs and behaviors
+of the GoAlert server component.
+
+Run the full suite with `make smoketest`.
+
+More information about smoketests can be found [here](../smoketest/README.md).
+
+### Running Unit Tests
+
+All unit tests can be run with `make test`.
+
+UI Unit tests are found under the directory of the file being tested, with the same file name, appended with `.test.js`. They can be run independently of the Go unit tests with `make jest`. Watch mode can be enabled with `make jest JEST_ARGS=--watch`.