Skip to content

Latest commit

 

History

History
156 lines (100 loc) · 3.75 KB

CONTRIBUTING.md

File metadata and controls

156 lines (100 loc) · 3.75 KB
Raw

Exposure Server Components - contribution guidelines

Contributions to this project are welcomed. We request that you read through the guidelines before getting started.

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.

Community guidelines

This project follows Google's Open Source Community Guidelines.

Contribution

Code reviews

All submissions will be reviewed before merging. Submissions are reviewed using GitHub pull requests.

Source and build

Source code layout

Common code is in the /pkg folder.

Each binary will have its main.go file in a /cmd/[bin-name] folder.

Installing project dependencies

To run the server, you must install the following dependencies:

  1. Go 1.14.0 or newer.

  2. Docker.

Running tests

Run the tests with:

$ go test ./...

To run tests that interact with the database:

  1. Set up the environment:

    $ eval $(./scripts/dev init)

  2. Start a local database instance:

    $ ./scripts/dev dbstart

  3. Run the tests:

    $ go test -v ./...

Presubmit checks

You should run the presubmit checks before committing changes. The presubmit script is located at scripts/presubmit.sh.

You can add a prepush hook by linking to the presubmit script to automatically run before pushing a branch to the remote GitHub repository. To add the presubmit script as a prepush hook, go to the root directory of the repository and type:

ln -s -f ../../scripts/presubmit.sh .git/hooks/pre-push
chmod a+x .git/hooks/pre-push

Running locally

These instructions use Docker to run components locally. You may be able to run these components without Docker, but these instructions assume Docker is installed and available in your $PATH.

  1. Set development environment variables:

    $ eval $(./scripts/dev init)

    If you close your terminal tab or session, you will need to re-run this command.

  2. Create the local development database:

    $ ./scripts/dev dbstart

    This command may take a few minutes to execute on the first invocation. This is because it needs to download the Postgres container. Future invocations will be faster.

  3. Run any migrations. This creates the tables and schema:

    $ ./scripts/dev dbmigrate

  4. (Optional) Seed the database with some initial data:

    $ ./scripts/dev dbseed

  5. Run a component. For example, to run the exposure endpoint:

    $ go run ./cmd/exposure/...

    Alternatively, you can run all the server components as a single binary with each component at a different path:

    $ go run ./cmd/monolith/...

  6. When you're done developing, you can stop the database.

    $ ./scripts/dev dbstop

    Warning: This will also delete any stored data in the database.

Documentation

User documentation for this project is in the docs directory, with information on building, deploying, and using the reference implementation.