1# Contributing to the MongoDB Go Driver
2
3Thank you for your interest in contributing to the MongoDB Go Driver!
4
5We are building this software together and strongly encourage contributions from the community that are within the guidelines set forth below.
6
7## Requirements
8
9Go 1.20 or higher is required to run the driver test suite.
10
11## Bug Fixes and New Features
12
13Before starting to write code, look for existing [tickets](https://jira.mongodb.org/browse/GODRIVER) or [create one](https://jira.mongodb.org/secure/CreateIssue!default.jspa) for your bug, issue, or feature request. This helps the community avoid working on something that might not be of interest or which has already been addressed.
14
15## Pull Requests & Patches
16
17The Go Driver team uses GitHub to manage and review all code changes. Patches should generally be made against the master (default) branch and include relevant tests, if
18applicable.
19
20Code should compile and tests should pass under all Go versions which the driver currently supports. Currently the Go Driver supports a minimum version of Go 1.18 and requires Go 1.20 for development. Please run the following Make targets to validate your changes:
21
22- `make fmt`
23- `make lint` (requires [golangci-lint](https://github.com/golangci/golangci-lint) and [lll](https://github.com/walle/lll) to be installed and available in the `PATH`)
24- `make test`
25- `make test-race`
26
27**Running the tests requires that you have a `mongod` server running on localhost, listening on the default port (27017). At minimum, please test against the latest release version of the MongoDB server.**
28
29If any tests do not pass, or relevant tests are not included, the patch will not be considered.
30
31If you are working on a bug or feature listed in Jira, please include the ticket number prefixed with GODRIVER in the commit message and GitHub pull request title, (e.g. GODRIVER-123). For the patch commit message itself, please follow the [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) guide.
32
33### Linting on commit
34
35The Go team uses [pre-commit](https://pre-commit.com/#installation) to lint both source and text files.
36
37To install locally, run:
38
39```bash
40brew install pre-commit
41pre-commit install
42```
43
44After that, the checks will run on any changed files when committing. To manually run the checks on all files, run:
45
46```bash
47pre-commit run --all-files
48```
49
50### Cherry-picking between branches
51
52You must first install the `gh` cli (`brew install gh`), then set your GitHub username:
53
54```bash
55git config --global github.user <github_handle>
56```
57
58If a Pull Request needs to be cherry-picked to a new branch, get the sha of the commit in the base branch, and then run
59
60```bash
61bash etc/cherry-picker.sh <sha>
62```
63
64The cherry-picker script is configured to use `v1` as the base branch and `master` as the target branch.
65It will create a new checkout in a temp dir, create a new branch, perform the cherry-pick, and then
66prompt before creating a PR to the target branch.
67
68## Testing / Development
69
70The driver tests can be run against several database configurations. The most simple configuration is a standalone mongod with no auth, no ssl, and no compression. To run these basic driver tests, make sure a standalone MongoDB server instance is running at localhost:27017. To run the tests, you can run `make` (on Windows, run `nmake`). This will run coverage, run go-lint, run go-vet, and build the examples.
71
72You can install `libmongocrypt` locally by running `bash etc/build-libmongocrypt.sh`, which will create an `install` directory
73in the repository top level directory. On Windows you will also need to add `c:/libmongocrypt/` to your `PATH`.
74
75### Testing Different Topologies
76
77To test a **replica set** or **sharded cluster**, set `MONGODB_URI="<connection-string>"` for the `make` command.
78For example, for a local replica set named `rs1` comprised of three nodes on ports 27017, 27018, and 27019:
79
80```
81MONGODB_URI="mongodb://localhost:27017,localhost:27018,localhost:27019/?replicaSet=rs1" make
82```
83
84### Testing Auth and TLS
85
86To test authentication and TLS, first set up a MongoDB cluster with auth and TLS configured. Testing authentication requires a user with the `root` role on the `admin` database. Here is an example command that would run a mongod with TLS correctly configured for tests. Either set or replace PATH_TO_SERVER_KEY_FILE and PATH_TO_CA_FILE with paths to their respective files:
87
88```
89mongod \
90--auth \
91--tlsMode requireTLS \
92--tlsCertificateKeyFile $PATH_TO_SERVER_KEY_FILE \
93--tlsCAFile $PATH_TO_CA_FILE \
94--tlsAllowInvalidCertificates
95```
96
97To run the tests with `make`, set:
98
99- `MONGO_GO_DRIVER_CA_FILE` to the location of the CA file used by the database
100- `MONGO_GO_DRIVER_KEY_FILE` to the location of the client key file
101- `MONGO_GO_DRIVER_PKCS8_ENCRYPTED_KEY_FILE` to the location of the pkcs8 client key file encrypted with the password string: `password`
102- `MONGO_GO_DRIVER_PKCS8_UNENCRYPTED_KEY_FILE` to the location of the unencrypted pkcs8 key file
103- `MONGODB_URI` to the connection string of the server
104- `AUTH=auth`
105- `SSL=ssl`
106
107For example:
108
109```
110AUTH=auth SSL=ssl \
111MONGO_GO_DRIVER_CA_FILE=$PATH_TO_CA_FILE \
112MONGO_GO_DRIVER_KEY_FILE=$PATH_TO_CLIENT_KEY_FILE \
113MONGO_GO_DRIVER_PKCS8_ENCRYPTED_KEY_FILE=$PATH_TO_ENCRYPTED_KEY_FILE \
114MONGO_GO_DRIVER_PKCS8_UNENCRYPTED_KEY_FILE=$PATH_TO_UNENCRYPTED_KEY_FILE \
115MONGODB_URI="mongodb://user:password@localhost:27017/?authSource=admin" \
116make
117```
118
119Notes:
120
121- The `--tlsAllowInvalidCertificates` flag is required on the server for the test suite to work correctly.
122- The test suite requires the auth database to be set with `?authSource=admin`, not `/admin`.
123
124### Testing Compression
125
126The MongoDB Go Driver supports wire protocol compression using Snappy, zLib, or zstd. To run tests with wire protocol compression, set `MONGO_GO_DRIVER_COMPRESSOR` to `snappy`, `zlib`, or `zstd`. For example:
127
128```
129MONGO_GO_DRIVER_COMPRESSOR=snappy make
130```
131
132Ensure the [`--networkMessageCompressors` flag](https://www.mongodb.com/docs/manual/reference/program/mongod/#cmdoption-mongod-networkmessagecompressors) on mongod or mongos includes `zlib` if testing zLib compression.
133
134### Testing FaaS
135
136The requirements for testing FaaS implementations in the Go Driver vary depending on the specific runtime.
137
138#### AWS Lambda
139
140The following are the requirements for running the AWS Lambda tests locally:
141
1421. [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)
1431. [Docker](https://www.docker.com/products/docker-desktop/)
144
145Local testing requires exporting the `MONGODB_URI` environment variables. To build the AWS Lambda image and invoke the `MongoDBFunction` lambda function use the `build-faas-awslambda` make target:
146
147```bash
148MONGODB_URI="mongodb://host.docker.internal:27017" make build-faas-awslambda
149```
150
151The usage of host.docker.internal comes from the [Docker networking documentation](https://docs.docker.com/desktop/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host).
152
153There is currently no arm64 support for the go1.x runtime, see [here](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html). Known issues running on linux/arm64 include the inability to network with the localhost from the public.ecr.aws/lambda/go Docker image.
154
155### Encryption Tests
156
157Most of the tests requiring `libmongocrypt` can be run using the Docker workflow.
158
159However, some of the tests require secrets handling. Please see the team [Wiki](https://wiki.corp.mongodb.com/pages/viewpage.action?spaceKey=DRIVERS&title=Testing+CSFLE) for more information.
160
161The test suite can be run with or without the secrets as follows:
162
163```bash
164MAKEFILE_TARGET=evg-test-versioned-api bash .evergreen/run-tests.sh
165```
166
167### Load Balancer
168
169To launch the load balancer on MacOS, run the following.
170
171- `brew install haproxy`
172- Clone drivers-evergreen-tools and save the path as `DRIVERS_TOOLS`.
173- Start the servers using (or use the docker-based method below):
174
175```bash
176LOAD_BALANCER=true TOPOLOGY=sharded_cluster AUTH=noauth SSL=nossl MONGODB_VERSION=6.0 DRIVERS_TOOLS=$PWD/drivers-evergreen-tools MONGO_ORCHESTRATION_HOME=$PWD/drivers-evergreen-tools/.evergreen/orchestration $PWD/drivers-evergreen-tools/.evergreen/run-orchestration.sh
177```
178
179- Start the load balancer using:
180
181```bash
182MONGODB_URI='mongodb://localhost:27017,localhost:27018/' $PWD/drivers-evergreen-tools/.evergreen/run-load-balancer.sh start
183```
184
185- Run the load balancer tests (or use the docker runner below with `evg-test-load-balancers`):
186
187```bash
188make evg-test-load-balancers
189```
190
191### Testing in Docker
192
193We support local testing in Docker. To test using docker, you will need to set the `DRIVERS_TOOLs` environment variable to point to a local clone of the drivers-evergreen-tools repository. This is essential for running the testing matrix in a container. You can set the `DRIVERS_TOOLS` variable in your shell profile or in your project-specific environment.
194
1951. First, start the drivers-tools server docker container, as:
196
197```bash
198bash $DRIVERS_TOOLS/.evergreen/docker/start-server.sh
199```
200
201See the readme in `$DRIVERS_TOOLS/.evergreen/docker` for more information on usage.
202
2032. Next, start any other required services in another terminal, like a load balancer.
204
2051. Finally, run the Go Driver tests using the following script in this repo:
206
207```bash
208bash etc/run_docker.sh
209```
210
211The script takes an optional argument for the `MAKEFILE_TARGET` and allows for some environment variable overrides.
212The docker container has the required binaries, including libmongocrypt.
213The entry script executes the desired `MAKEFILE_TARGET`.
214
215For example, to test against a sharded cluster (make sure you started the server with a sharded_cluster),
216using enterprise auth, run:
217
218```bash
219TOPOLOGY=sharded_cluster bash etc/run_docker.sh evg-test-enterprise-auth
220```
221
222## Talk To Us
223
224If you want to work on the driver, write documentation, or have questions/complaints, please reach out to us either via [MongoDB Community Forums](https://www.mongodb.com/community/forums/tag/go-driver) or by creating a Question issue in [Jira](https://jira.mongodb.org/secure/CreateIssue!default.jspa).
View as plain text