You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+75-41
Original file line number
Diff line number
Diff line change
@@ -4,36 +4,32 @@ When contributing to this repository, please first discuss the change you wish
4
4
to make via issue, pull request, or any other method with the owners of this
5
5
repository before making a change.
6
6
7
-
Please note we have a [code of conduct][code-of-conduct],
8
-
please follow it in all your interactions with the project.
7
+
Please follow the [code of conduct][code-of-conduct] in all your interactions with the project.
9
8
10
9
## Developer Startup Guide
11
10
11
+
This section will walk you though how to get started working with the code.
12
12
### Runtime
13
13
14
-
It's recommended you install Node Version Manager for [unix systems][nvm-unix] or [windows][nvm-windows].
15
-
While it isn't required we have a minimum node version requirement (look in [package.json](./package.json) under the "engines" key) and we can't accept code that does not work on the minimum specified version.
14
+
We recommend you install Node Version Manager for [UNIX systems][nvm-unix] or [Windows][nvm-windows].
15
+
16
+
All code changes must work on the minimum Node version specified in [package.json](./package.json) under the "engines" key.
17
+
18
+
### Get the Code
19
+
20
+
Begin by cloning this repo. Then run `npm install` to install necessary dependencies.
16
21
17
22
### MongoDB Helpers
18
23
19
-
- For setting up a cluster to test against we recommend using [mtools][mtools-install].
24
+
The following tools will help you manage MongoDB locally on your machine.
25
+
- For setting up a cluster to test against, we recommend using [mtools][mtools-install].
20
26
- For managing installed versions of MongoDB, we recommend using [m](https://github.com./aheckmann/m).
21
27
22
-
### VSCode Setup
23
-
24
-
- Save the the workspace file [mongodbNodeDriver.code-workspace][workspace-file] next to where you have the driver cloned to and open this in VSCode.
25
-
Double check that the `folders.path` at the top of the file's json is correct.
One option to get up and running quickly is to use a preconfigured VS Code [workspace][workspace-file]. Save the the workspace file in a directory separate from the directory where you cloned this repo. Open the workspace file in VS Code, and update `folders.path` to point to your local `driver` directory.
35
31
36
-
If you just want to get formatting and linting working automatically use these settings:
32
+
Alternatively, if you just want to get formatting and linting working automatically without using the workspace file, add these settings to your VS Code code workspace:
37
33
38
34
```jsonc
39
35
"settings":{
@@ -49,37 +45,69 @@ If you just want to get formatting and linting working automatically use these s
- If you are running against more than a standalone make sure your ulimit settings are in accordance with mongo's recommendations
66
-
- Changing the settings on the latest versions of macos can be tricky: [read here][macos-ulimt] (unless you know you need it you shouldn't have to do the complicated maxproc steps)
70
+
71
+
You can use `test/tools/cluster_setup.sh replica_set` to start a replica set.
72
+
73
+
If you are running more than a standalone server, make sure your `ulimit` settings are in accordance with
74
+
[MongoDB's recommendations][mongodb-ulimit].
75
+
Changing the settings on the latest versions of macOS can be tricky. See [this article][macos-ulimt]
76
+
for tips. (You likely don't need to do the complicated maxproc steps.)
77
+
78
+
You can prefix `npm test` with a `MONGODB_URI` environment variable to point the tests to a specific deployment:
- To run a single test, use mocha's grep flag: `npm run test -- -g 'test name'`
69
-
- If it's easier you can also isolate tests by adding `.only` Example: `it.only(‘cool test’, function() {})`
82
+
83
+
The easiest way to run a single test is by appending `.only()` to the suite or test you want to run.
84
+
For example, you could update a test function to be `it.only(‘cool test’, function() {})`. Then
85
+
run the test using `npm run check:test` for a functional or integration test or
86
+
`npm run check:unit` for a unit test. See [Mocha's documentation][mocha-only]
87
+
for more detailed information on `.only()`.
88
+
89
+
Another way to run a single test is to use Mocha's `grep` flag. For functional or integration tests,
90
+
run `npm run check:test -- -g 'test name'`. For unit tests, run `npm run check:unit -- -g 'test name'`.
91
+
See the [Mocha documentation][mocha-grep] for information on the `grep` flag.
92
+
93
+
- Why are some of the tests "pending"?
94
+
95
+
Tests that we have indicated should be skipped using `.skip()` will appear as pending in the test
96
+
results. See
97
+
[Mocha's documentation][mocha-skip] for more information.
70
98
71
99
### Commit messages
72
100
73
-
Please follow the [conventional commit style][conventional-commit-style].
74
-
The format should look something like this (note the blank lines):
101
+
Please follow the [Conventional Commits specification][conventional-commit-style].
102
+
The format should look something like the following (note the blank lines):
75
103
76
104
```txt
77
105
<type>(<scope>): <subject>
78
106
79
107
<body>
80
108
```
81
109
82
-
If there is a relevant NODE ticket number it should be referenced in the scope portion of the commit.
110
+
If there is a relevant [NODE Jira ticket][node-jira], reference the ticket number in the scope portion of the commit.
83
111
84
112
Note that a BREAKING CHANGE commit should include an exclamation mark after the scope, for example:
85
113
@@ -96,7 +124,7 @@ These are the commit types we make use of:
96
124
-**style:** Changes that do not affect the meaning of the code (e.g, formatting)
97
125
-**refactor:** A code change that neither fixes a bug nor adds a feature
98
126
-**perf:** A code change that improves performance
99
-
-**test:**Adding missing or correcting existing tests
127
+
-**test:**Adds missing or corrects existing test(s)
100
128
-**chore:** Changes to the build process or auxiliary tools and libraries such as documentation generation
101
129
102
130
## Conventions Guide
@@ -106,11 +134,11 @@ Below are some conventions that aren't enforced by any of our tooling but we non
106
134
-**Disallow `export default` syntax**
107
135
- For our use case it is best if all imports / exports remain named.
108
136
-**As of 4.0 all code in src is in Typescript**
109
-
- Typescript provides a nice developer experience
110
-
As a product of using TS we should be using es6 syntax features whenever possible.
137
+
- Typescript provides a nice developer experience.
138
+
As a product of using TS, we should be using ES6 syntax features whenever possible.
111
139
-**Errors**
112
-
- Error messages should be sentence case, and have no periods at the end.
113
-
- Use driver-specific error types where possible (not just `Error`, but classes that extend `MongoError`, e.g. `MongoNetworkError`)
140
+
- Error messages should be sentence case and have no periods at the end.
141
+
- Use driver-specific error types where possible (not just `Error`, but classes that extend `MongoError`, e.g. `MongoNetworkError`).
114
142
115
143
## Pull Request Process
116
144
@@ -144,14 +172,14 @@ Reviewers should use the following questions to evaluate the implementation for
144
172
- better organized / easier to understand / clearer separation of concerns
145
173
- easier to maintain (easier to change, harder to accidentally break)
146
174
- Housekeeping
147
-
1. Does the title and description of the PR reference the correct jira ticket and does it use the correct conventional commit type (e.g., fix, feat, test, breaking change etc)?
175
+
1. Does the title and description of the PR reference the correct Jira ticket and does it use the correct conventional commit type (e.g., fix, feat, test, breaking change etc)?
148
176
- If the change is breaking, ensure there is an exclamation mark after the scope (e.g., "fix(NODE-xxx)!: \<description\>" )
149
-
1. If there are new TODOs, has a related JIRA ticket been created?
177
+
1. If there are new TODOs, has a related Jira ticket been created?
150
178
1. Are symbols correctly marked as internal or public?
151
179
1. Do the Typescript types match expected runtime usage? Are there tests for new or updated types?
152
180
1. Should any documentation be updated?
153
181
- Has the relevant internal documentation been updated as part of the PR?
154
-
- Have the external documentation requirements been captured in jira?
182
+
- Have the external documentation requirements been captured in Jira?
0 commit comments