peregrine-backend

README

Peregrine

Peregrine is a HTTP JSON API written in Go for scouting and analysis of FIRST Robotics competitions.

For a description of what scouting is, please view the SCOUTING.md.

Setup

1. Install Git and Go (>=1.11)
2. Clone the repo:

git clone git@github.com:Pigmice2733/peregrine-backend.git

1. Change directory to the repo root:

cd peregrine-backend

1. Install PostgreSQL and start the server.

2. Install the migrate and peregrine binaries:

NOTE: If you cloned the repo to somewhere in your GOPATH (e.g. with go get) you'll need to export GO111MODULE=on.

go generate ./... # neccessary to compile OpenAPI documentation into the binary
go install ./...

1. Create the postgres database:

createdb -U postgres peregrine

1. Copy the config template:

cp etc/config.yaml.template etc/config.development.yaml

1. Modify etc/config.development.yaml as neccesary. You will likely not need to change anything besides the TBA API key if you followed the instructions here. You will need to go to the TBA account page and get a read API key and set apiKey under the tba section to the read API key you register.
2. Run the database migrations:

migrate -up

1. Run the app:

peregrine

API Documentation

Peregrine's entire API is documented with OpenAPI 3.0.0 (previously known as Swagger). You can view the documentation here, or by running peregrine locally and going here. If you notice any inaccuracies please let us know so the documentation can be corrected.

Testing

Peregrine has both unit tests and integration tests. Both should be passing for a new feature.

Unit tests

Run go test:

go test ./...

Integration (jest) tests

You must have a server running for integration tests. See the setup section.

1. Go to the api-tests folder:

cd api-tests

1. Install dependencies:

npm i

1. Set the GO_ENV environment variable if you used Docker to setup the app:

export GO_ENV="docker"

1. Run the tests:

npm test

Contributing

1. Create a branch with a name that briefly describes the feature (e.g. report-endpoints):

git checkout -b report-endpoints

1. Add your commits to the branch:

git add internal/foo/bar.go
git commit -m "Add the initial report endpoints"

1. Verify that your tests pass (see the testing section). If they don't then fix them and add a commit.

2. Push the branch to the remote github repo:

git push -u origin report-endpoints

1. Visit the project on Github, go to Pull Requests, and hit New Pull Request.
2. Fill out the template.
3. Assign relevant reviewers, assign yourself, add any applicable labels, assign any applicable projects, and hit Create Pull Request.