217 lines
7.1 KiB
Markdown
217 lines
7.1 KiB
Markdown
# Contributing to Threshold
|
|
|
|
Thank you for contributing to Threshold! Threshold is a community fork of HashiCorp Boundary Community Edition (CE).
|
|
It is not affiliated with or endorsed by HashiCorp or IBM. Here you can find common questions around reporting issues
|
|
and opening pull requests to the project. The repository lives at
|
|
<https://repo.anhonesthost.net/CyberCoveLLC/threshold>.
|
|
|
|
Please be respectful and inclusive when contributing in any way (new issue, PR, etc).
|
|
|
|
## Issue Reporting
|
|
### Reporting Security Related Vulnerabilities
|
|
|
|
If you believe you have found a security issue in Threshold, please disclose it responsibly by contacting the
|
|
maintainers privately rather than opening a public issue. Issues that exist in upstream HashiCorp Boundary CE should
|
|
also be treated as security-sensitive.
|
|
|
|
### Bug Fixes
|
|
|
|
If you believe you found a bug with Threshold, please:
|
|
|
|
1. Build from the latest `main` HEAD commit to attempt to reproduce the issue. It's possible it has already been fixed.
|
|
1. Ensure a similar issue is not already opened by searching the open issues in the repository.
|
|
|
|
Once you've verified the above, open an issue in the repository describing how to reproduce the problem.
|
|
|
|
## Pull Requests
|
|
|
|
### New Features & Improvements
|
|
|
|
Before writing a line of code, please open an issue to discuss a potential improvement or feature. Threshold is
|
|
focused on maintaining the Community Edition code base, so changes that stay close to upstream behavior and
|
|
compatibility are the easiest to accept.
|
|
|
|
### Submitting a New Pull Request
|
|
|
|
When submitting a pull request, please ensure:
|
|
|
|
1. You've added a changelog line clearly describing the new addition under the correct changelog sub-section.
|
|
1. You've followed the above guidelines for contributing to Threshold.
|
|
|
|
## Changelog
|
|
|
|
The changelog is updated by PR contributors. Each contribution to Threshold should include a changelog update at the contributor or reviewer discretion.
|
|
The changelog should be updated when the contribution is large enough to warrant it being called out in the larger release cycle. Enhancements, bug fixes,
|
|
and other contributions that practitioners might want to be aware of should exist in the changelog.
|
|
|
|
When contributing to the changelog, follow existing patterns for referencing PR's, issues or other ancillary context.
|
|
|
|
The changelog is broken down into sections:
|
|
|
|
### vNext
|
|
|
|
The current release cycle. New contributions slated for the next release should go under this heading. If the contribution is being backported,
|
|
the inclusion of the feature in the appropriate release during the backport process is handled on an as-needed basis.
|
|
|
|
### New and Improved
|
|
|
|
Any enhancements, new features, etc fall into this section.
|
|
|
|
### Bug Fixes
|
|
|
|
Any bug fixes fall into this section.
|
|
|
|
## Testing
|
|
|
|
Most tests require a postgres database instance to successfully run.
|
|
This is provided via docker
|
|
by running a customized postgres image that is optimized for Threshold tests.
|
|
|
|
Before running the test suite, this docker container must be started:
|
|
|
|
```
|
|
$ make test-database-up
|
|
```
|
|
|
|
This can take a few seconds to initialize as it will
|
|
create a template database with the boundary migrations.
|
|
The progress can be checked b running:
|
|
|
|
```
|
|
$ docker logs -f boundary-sql-tests
|
|
```
|
|
|
|
Once a log line like the following is seen, the container is ready for running
|
|
tests:
|
|
|
|
```
|
|
PostgreSQL init process complete; ready for start up.
|
|
```
|
|
|
|
Alternatively if the `pg_isready` command is installed, it can be used to
|
|
determine if the container is ready, i.e.:
|
|
|
|
```
|
|
$ until pg_isready -h 127.0.0.1; do sleep 1; done
|
|
```
|
|
|
|
To run the entire test suite run this command in the root of the project
|
|
once the test database is ready:
|
|
|
|
```
|
|
$ make test
|
|
```
|
|
|
|
Before running any test please ensure that Docker is started. Threshold uses a Docker container to initiate a database for testing.
|
|
If a test is interrupted check to make certain that all Docker containers have been properly destroyed.
|
|
|
|
### Running individual tests
|
|
|
|
If you don't want to run the entire test suite, you can just run a single test
|
|
with go. For example, if you wanted to run the tests TestAuthTokenAuthenticator, you would
|
|
run:
|
|
|
|
```
|
|
$ go test -run TestAuthTokenAuthenticator -v ./internal/auth
|
|
```
|
|
|
|
### Stopping the test database container
|
|
|
|
The test database container can be shutdown using:
|
|
|
|
```
|
|
$ make test-database-down
|
|
```
|
|
|
|
Note that the container does *not* need to be shutdown between each run of
|
|
`make test` or `go test`.
|
|
|
|
### Test database container options
|
|
|
|
By default the container uses the host port of 5432.
|
|
This can changed using an environment variable:
|
|
|
|
```
|
|
$ export TEST_DB_PORT=5433
|
|
$ make test-database-up
|
|
$ make test
|
|
```
|
|
|
|
By default the container name is `boundary-sql-tests`.
|
|
This can be changed in the same way as the port:
|
|
|
|
```
|
|
$ export TEST_CONTAINER_NAME="custom-name"
|
|
$ make test-database-up
|
|
$ docker logs custom-name
|
|
```
|
|
|
|
The default docker image is built using the `postgres:12` base image.
|
|
The image can be changed using a make option to test against other versions:
|
|
|
|
```
|
|
$ make IMAGE_TAG=docker.io/hashicorpboundary/postgres:12-alpine test-database-up
|
|
$ make IMAGE_TAG=docker.io/hashicorpboundary/postgres:13-alpine test-database-up
|
|
$ make IMAGE_TAG=docker.io/hashicorpboundary/postgres:alpine test-database-up
|
|
```
|
|
|
|
Additional options can be passed to postgres to customize and override the
|
|
configuration in the config file of the docker image.
|
|
See the troubleshooting section below for more details.
|
|
|
|
### Troubleshooting test database container
|
|
|
|
The postgres configuration file included in the image
|
|
is optimized to support running the full test suite in parallel in CI.
|
|
As such, there may be issues starting the container locally,
|
|
especially in cases where the container has less then 4GB of memory.
|
|
|
|
This is likely the case if the output of `docker logs boundary-sql-tests` shows:
|
|
|
|
```
|
|
pg_ctl: could not start server
|
|
```
|
|
|
|
In this case adjust the
|
|
[max_connections](https://www.postgresql.org/docs/11/runtime-config-connection.html#GUC-MAX-CONNECTIONS)
|
|
and/or
|
|
[shared_buffers](https://www.postgresql.org/docs/11/runtime-config-resource.html#GUC-SHARED-BUFFERS):
|
|
|
|
```
|
|
make PG_OPTS="-c max_connections=1000" test-database-up
|
|
```
|
|
|
|
Note that if `max_connections` is set too low, it may result in sporadic test
|
|
failures if a connection cannot be established. In this case, reduce the number
|
|
of concurrent tests via `GOMAXPROCS` or selectively run tests.
|
|
|
|
### SDK and API tests
|
|
|
|
Tests for the SDK and API modules can also be run. These do not require a test
|
|
database:
|
|
|
|
```
|
|
$ make test-api
|
|
$ make test-sdk
|
|
```
|
|
|
|
Or all of the test can be run with a single target:
|
|
|
|
```
|
|
$ make test-all
|
|
```
|
|
|
|
## Performance
|
|
### Database Indexes
|
|
|
|
Most of the indexes in the database are for enforcing data constraints.
|
|
We have not added indexes for improving performance because we do not have a way
|
|
to measure and test these types of indexes.
|
|
We want a way to test and verify that indexes added to improve performance are actually being used by the system.
|
|
And we want these same tests to fail when an index stops being used as we evolve the system.
|
|
This is on our roadmap but we have not started work on it yet.
|
|
|
|
## Additional docs
|
|
|
|
* [Adding fields to the API](internal/adding-a-new-field-readme.md)
|