|
1 | 1 | ---
|
2 |
| -# cSpell:ignore zerolog |
| 2 | +# cSpell:ignore zerolog jsonnet |
3 | 3 | title: Contributing
|
4 | 4 | lang: en-US
|
5 | 5 | keywords: [pomerium, community, contributing, pr, code]
|
@@ -42,6 +42,41 @@ Here are some of the expectations we have of contributors:
|
42 | 42 | - [Best Practices for Maintainers](https://opensource.guide/best-practices/)
|
43 | 43 | - [Shrinking Code Review](https://alexgaynor.net/2015/dec/29/shrinking-code-review/)
|
44 | 44 |
|
| 45 | +### Development |
| 46 | + |
| 47 | +See [Building Pomerium From Source](/docs/deploy/core/from-source) for information on getting started developing for Pomerium. |
| 48 | + |
| 49 | +To run the unit tests locally: |
| 50 | + |
| 51 | +```bash |
| 52 | +make test |
| 53 | +``` |
| 54 | + |
| 55 | +The instrumentation tests run using [Docker Compose]. To run the instrumentation tests locally, first build a development Docker image: |
| 56 | + |
| 57 | +```bash |
| 58 | +./scripts/build-dev-docker.bash |
| 59 | +``` |
| 60 | + |
| 61 | +Next pick a configuration from the `integration/clusters` directory, for example `single-stateful`, and use Docker Compose to start that configuration. Use the `POMERIUM_TAG` environment variable to specify the `dev` docker image built in the previous step: |
| 62 | + |
| 63 | +```bash |
| 64 | +cd integration/clusters/single-stateful |
| 65 | +env POMERIUM_TAG=dev docker compose up -V |
| 66 | +``` |
| 67 | + |
| 68 | +Once that's up and running you can run the integration tests from another terminal: |
| 69 | + |
| 70 | +```bash |
| 71 | +go test -count=1 -v ./integration/... |
| 72 | +``` |
| 73 | + |
| 74 | +If you need to make a change to the test configuration itself, there's a [tpl](https://github.com/pomerium/pomerium/tree/main/integration/tpl) folder that contains `jsonnet` files. Make a change and then rebuild the configuration by running: |
| 75 | + |
| 76 | +```bash |
| 77 | +go run ./integration/cmd/pomerium-integration-tests/ generate-configuration |
| 78 | +``` |
| 79 | + |
45 | 80 | ### Logging
|
46 | 81 |
|
47 | 82 | Pomerium uses the [zerolog](https://github.com/rs/zerolog) package for logging. Guidelines for log levels:
|
@@ -100,6 +135,7 @@ To add a new document to the side or top-bar navigation, see `docs/.vuepress/con
|
100 | 135 | We use [Netlify](https://www.netlify.com) to build and host our docs. One of nice features of Netlify, is that a preview of the docs are automatically created for each new pull request that is made, which lets you be sure that the version of your docs that you see locally match what will ultimately be deployed in production.
|
101 | 136 |
|
102 | 137 | [configuration variables]: /docs/reference
|
| 138 | +[docker compose]: https://docs.docker.com/compose/ |
103 | 139 | [download]: https://github.com/pomerium/pomerium/releases
|
104 | 140 | [environmental configuration variables]: https://12factor.net/config
|
105 | 141 | [verify]: https://verify.pomerium.com/
|
|
0 commit comments