Skip to content

Commit e225ee5

Browse files
nbbeekennbbeeken
authored
docs: Adds developer setup to contributor guide
 Describe how to get the driver dev environment up and running
1 parent c16ec43 commit e225ee5

File tree

1 file changed

+194
-3
lines changed

1 file changed

+194
-3
lines changed

‎CONTRIBUTING.md

Lines changed: 194 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,214 @@ repository before making a change.
77
Please note we have a [code of conduct][code-of-conduct],
88
please follow it in all your interactions with the project.
99

10-
## Commit messages
10+
## Developer Startup Guide
11+
12+
### Runtime
13+
14+
It's recommended you install Node Version Manager for [unix systems][nvm-unix] or [windows][nvm-windows]. While it isn't required we have a minimum node version requirement (look in package.json under the "engines" key) and we can't accept code that does not work on the minimum specified version.
15+
16+
### MongoDB Helpers
17+
18+
- To get various MongoDB topologies up and running easily you can use the python based tool [mtools][mtools-install].
19+
- To get various versions of MongoDB to test against you can use [m](https://github.com/aheckmann/m) an npm tool best installed globally `npm i -g m`.
20+
21+
### VSCode Setup
22+
23+
If you are developing in VSCode here's some suggestions:
24+
We have an example of our workspace file: save this as `mongodbNodeDriver.code-workspace` and replace PATH_TO_DRIVER with the path to the driver repository on your computer.
25+
26+
<details>
27+
<summary>mongodbNodeDriver.code-workspace</summary>
28+
<br>
29+
<pre lang="jsonc">
30+
{
31+
"folders": [
32+
{
33+
"path": "PATH_TO_DRIVER",
34+
"name": "driver"
35+
}
36+
],
37+
"settings": {
38+
"search.exclude": {
39+
// I always set 'file to include' in search to:
40+
// - src
41+
// - test
42+
// - {test|src}
43+
"**/node_modules": false, // searching node_modules comes in handy
44+
"./lib": true, // by default I don't want results from our compiled source
45+
"**/bower_components": true,
46+
"**/*.code-search": true
47+
},
48+
// ts gives me the power to not rely on word matching
49+
"editor.wordBasedSuggestions": false,
50+
"gitlens.hovers.enabled": false,
51+
"editor.codeActionsOnSave": {
52+
"source.fixAll.eslint": true
53+
},
54+
"[javascript]": {
55+
"editor.defaultFormatter": "dbaeumer.vscode-eslint"
56+
},
57+
"[typescript]": {
58+
"editor.defaultFormatter": "dbaeumer.vscode-eslint",
59+
"editor.codeActionsOnSave": {
60+
"source.organizeImports": false
61+
}
62+
},
63+
"eslint.enable": true,
64+
"eslint.format.enable": true,
65+
"mochaExplorer.files": "test/{functional,unit}/**/*.test.js",
66+
"mochaExplorer.ui": "test/tools/runner/metadata_ui.js",
67+
"editor.formatOnSave": false,
68+
"editor.rulers": [100],
69+
"editor.renderWhitespace": "selection",
70+
"files.trimTrailingWhitespace": true,
71+
"files.trimFinalNewlines": true,
72+
"files.insertFinalNewline": true,
73+
"typescript.tsdk": "node_modules/typescript/lib",
74+
// I leave the coverage extension disabled when not using it so I leave these commented
75+
// but these settings are nice when it is enabled
76+
// "coverage-gutters.showGutterCoverage": false,
77+
// "coverage-gutters.showLineCoverage": true,
78+
},
79+
"launch": {
80+
"configurations": [
81+
{
82+
// Sometimes I need to run mocha myself and not via the sidebar
83+
// Here I can add custom args or env variables
84+
"name": "run mocha",
85+
"type": "pwa-node",
86+
"request": "launch",
87+
"program": "node_modules/.bin/mocha",
88+
"args": ["test/unit", "test/functional"]
89+
}
90+
],
91+
"compounds": []
92+
},
93+
"tasks": {
94+
"version": "2.0.0",
95+
"tasks": [
96+
{
97+
// Here is an optional watcher task (`npm test` will also type check you changes):
98+
// Since this is the default build task it can be started with cmd+shift+b
99+
// There will be a wrench and screw icon
100+
// on the bottom bar where you can quick check build issues
101+
"label": "watch TS",
102+
"command": "npx",
103+
"type": "shell",
104+
"args": ["tsc", "-w"],
105+
"problemMatcher": "$tsc-watch",
106+
"isBackground": true,
107+
"group": {
108+
"kind": "build",
109+
"isDefault": true
110+
}
111+
}
112+
]
113+
},
114+
"extensions": {
115+
"recommendations": [
116+
"dbaeumer.vscode-eslint",
117+
"hbenl.vscode-test-explorer",
118+
"hbenl.vscode-mocha-test-adapter",
119+
"ryanluker.vscode-coverage-gutters",
120+
"github.vscode-pull-request-github",
121+
"mongodb.mongodb-vscode"
122+
],
123+
"unwantedRecommendations": ["esbenp.prettier-vscode"]
124+
}
125+
}
126+
</pre>
127+
</details>
128+
129+
If you use this file you will get our recommended extensions suggested to you.
130+
If not, we recommend picking up `dbaeumer.vscode-eslint` at least to make sure any additional code is following style recommendations. If you don't want to use this workspace file but still don't want to think about formatting you can have VSCode do the checks and formatting work for you by adding just these settings:
131+
132+
```jsonc
133+
"settings":{
134+
"editor.codeActionsOnSave": {
135+
"source.fixAll.eslint": true
136+
},
137+
"[javascript]": {
138+
"editor.defaultFormatter": "dbaeumer.vscode-eslint"
139+
},
140+
"[typescript]": {
141+
"editor.defaultFormatter": "dbaeumer.vscode-eslint",
142+
}
143+
}
144+
```
145+
146+
### Running the tests
147+
148+
Running the tests:
149+
150+
- You can use the script: `test/tools/cluster_setup.sh server`
151+
- If you are running against more than a standalone make sure your ulimit settings are in accordance with mongo's recommendations
152+
- 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)
153+
- Prefix the cluster_setup.sh script with `env MONGODB_VERSION=X.Y` to test against a specific version of the server
154+
- `env MONGODB_URI=mongodb://localhost:27017 npm test`
155+
- When testing different topologies you may need to remove the existing data folder created.
156+
- To run a single test, use `npm run test -- -g 'test name'`
157+
- If it's easier you can also isolate tests by adding .only. Example: `it.only(‘cool test’, {})`
158+
- To test only the unified topology, use `env MONGODB_UNIFIED_TOPOLOGY=1`
159+
160+
### Commit messages
11161

12162
Please follow the [Angular commit style][angular-commit-style].
163+
The format should look something like this (note the blank lines):
164+
165+
```txt
166+
<type>(<scope>): <subject>
167+
168+
<body>
169+
170+
NODE-XXXX
171+
```
172+
173+
If there is a relevant NODE ticket number it should be in the footer section of the Angular style commit.
174+
13175
This helps the team automate [HISTORY.md](HISTORY.md) generation.
176+
These are the commit types we make use of:
177+
178+
- **feat:** A new feature
179+
- **fix:** A bug fix
180+
- **docs:** Documentation only changes
181+
- **style:** Changes that do not affect the meaning of the code (e.g, formatting)
182+
- **refactor:** A code change that neither fixes a bug nor adds a feature
183+
- **perf:** A code change that improves performance
184+
- **test:** Adding missing or correcting existing tests
185+
- **chore:** Changes to the build process or auxiliary tools and libraries such as documentation generation
186+
187+
## Conventions Guide
188+
189+
Below are some conventions that aren't enforced by any of our tooling but we nonetheless do our best to adhere to:
190+
191+
- **Disallow `async / await` syntax**
192+
- There is a measurable overhead to Promise usage vs simple callbacks. To support the broadest of driver usage scenarios we maintain an internal callback api while exposing a surface layer Promise API.
193+
- **Disallow `export default` syntax**
194+
- For our use case it is best if all imports / exports remain named.
195+
- **As of 4.0 all code in src is in Typescript**
196+
- Typescript provides a nice developer experience. As a product of using TS we should be using es6 syntax features whenever possible.
197+
- **Errors**
198+
- Error messages should be sentence case, and have no periods at the end.
199+
- Use built-in error types where possible (not just Error, but TypeError/RangeError), also endeavor to create new Mongo-specific error types (e.g. MongoNetworkError)
14200

15201
## Pull Request Process
16202

17203
1. Update the README.md or similar documentation with details of changes you
18204
wish to make, if applicable.
19205
2. Add any appropriate tests.
20206
3. Make your code or other changes.
21-
4. Review guidelines such as
22-
[How to write the perfect pull request][github-perfect-pr], thanks!
207+
4. Review guidelines such as [How to write the perfect pull request][github-perfect-pr], thanks!
23208

209+
Take a look at [Github Flow][github-flow] for a more detailed explanation of this process.
24210

25211
[angular-commit-style]: https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits
26212
[changelog]: CHANGELOG.md
27213
[code-of-conduct]: CODE_OF_CONDUCT.md
28214
[github-perfect-pr]: https://blog.github.com/2015-01-21-how-to-write-the-perfect-pull-request/
29215
[mdb-core-values]: https://www.mongodb.com/company/
216+
[mtools-install]: http://blog.rueckstiess.com/mtools/install.html
217+
[nvm-windows]: https://github.com/coreybutler/nvm-windows#installation--upgrades
218+
[nvm-unix]: https://github.com/nvm-sh/nvm#install--update-script
219+
[macos-ulimt]: https://wilsonmar.github.io/maximum-limits/
220+
[github-flow]: https://guides.github.com/introduction/flow/

0 commit comments

Comments
 (0)