Contributing
First of all, thank you for considering contributing to Pomerium! You can have a direct impact on Pomerium by helping with its code or documentation.
- To contribute to Pomerium, open a pull request (PR) to the Pomerium repository
- To contribute to the documentation, open a PR to the documentation repository
If you're new to our community, that's okay: we gladly welcome pull requests from anyone, regardless of your native language or coding experience.
General
We try to hold contributions to a high standard for quality, so don't be surprised if we ask for revisions--even if it seems small or insignificant. Please don't take it personally. If your change is on the right track, we can guide you to make it mergeable.
Here are some of the expectations we have of contributors:
-
If your change is more than just a minor alteration, open an issue to propose your change first. This way we can avoid confusion, coordinate what everyone is working on, and ensure that changes are in-line with the project's goals and the best interests of its users. If there's already an issue about it, comment on the existing issue to claim it.
-
Keep pull requests small. Smaller PRs are more likely to be merged because they are easier to review! We might ask you to break up large PRs into smaller ones. An example of what we DON'T do.
-
Keep related commits together in a PR. We do want pull requests to be small, but you should also keep multiple related commits in the same PR if they rely on each other.
-
Write tests. Tests are essential! Written properly, they ensure your change works, and that other changes in the future won't break your change. CI checks should pass.
-
Benchmarks should be included for optimizations. Optimizations sometimes make code harder to read or have changes that are less than obvious. They should be proven with benchmarks or profiling.
-
Squash insignificant commits. Every commit should be significant. Commits which merely rewrite a comment or fix a typo can be combined into another commit that has more substance. Interactive rebase can do this, or a simpler way is
git reset --soft <diverging-commit>thengit commit -s. -
Own your contributions. Pomerium is a growing project, and it's much better when individual contributors help maintain their change after it is merged.
-
Use comments properly. We expect good godoc comments for package-level functions, types, and values. Comments are also useful whenever the purpose for a line of code is not obvious.
Versioning
Pomerium uses Semantic Versioning. In practice, this means for a given version number vMAJOR.MINOR.PATCH (for example, v0.1.0):
- MAJOR indicates an incompatible API change
- MINOR indicates a new, backwards-compatible functionality
- PATCH indicates a backwards-compatible bug fix
As Pomerium is still pre-v1.0.0, you should expect breaking changes between releases.
Development
See Building Pomerium From Source for information on getting started developing for Pomerium.
To run the unit tests locally:
make test
The instrumentation tests run using Docker Compose. To run the instrumentation tests locally, first build a development Docker image:
./scripts/build-dev-docker.bash
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:
cd integration/clusters/single-stateful
env POMERIUM_TAG=dev docker compose up -V
Once that's up and running you can run the integration tests from another terminal:
go test -count=1 -v ./integration/...
If you need to make a change to the test configuration itself, there's a tpl folder that contains jsonnet files. Make a change and then rebuild the configuration by running:
go run ./integration/cmd/pomerium-integration-tests/ generate-configuration
Logging
Pomerium uses the zerolog package for logging. Guidelines for log levels:
| Level | When to use |
|---|---|
| Panic | Do not use. Use Fatal instead. |
| Fatal | For unrecoverable errors at startup, or extremely exceptional circumstances at normal runtime. |
| Error | Something has failed, and an operator should know about it. |
| Warning | Do not use. Use Info or Error instead. |
| Info | An operator should want to see this during normal operation or routine inspection. |
| Debug | Verbose operational information that might be useful during troubleshooting. |
| Trace | Information that you would care about only when trying to understand code behavior/ordering/interaction. Intended for someone looking at or familiar with the code, not most end users. |
Docs
Pomerium's documentation is available at https://www.pomerium.io/docs. If you find a typo, feel a section could be better described, or have an idea for a totally new application or section, don't hesitate to make a PR change. There are few ways you can do this.
Simple edits
The easiest way to fix minor documentation issues in Pomerium is to click on the Edit this page link at the bottom of any page.
Doing so will redirect you to the the respective file in the Documentation repository. Here, you can update the page and commit your changes.
Committing your changes will create a new branch and start a PR.
Bigger changes
If you need to add a new page, or would like greater control over the editing process you can edit the docs similar to how you would make changes to the source code.
Prerequisites
We use Docusaurus to generate our docs. Docusaurus is a React-powered static-site generator designed for documentation.
Before building the docs, you'll need the following packages:
Make changes
Once you've installed Node and Yarn, in a terminal run the following command:
yarn start
You should see a link to the development server:
[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3001/
Once you have the development server up and running, any changes you make will automatically be reloaded and accessible in your browser.
To add a new document, simply add a new file with the .md markdown extension. For example, this document would be docs/community/contributing.md.
To make changes to the sidebar or navigation, see the following Docusaurus docs for instructions:
PR previews
We use Netlify to build and host our docs. A nice feature of Netlify is the Deploy Preview URL, which generates a link for PRs. This is helpful if you want to compare your local changes to what will ultimately be deployed in production.
After you've pushed your PR, a member of the documentation team will review your PR and communicate any next steps or suggestions before the PR is merged.