69 lines
2.0 KiB
Markdown
69 lines
2.0 KiB
Markdown
# Contributing to Motor
|
|
|
|
Contributions are encouraged. Please read these guidelines before
|
|
sending a pull request.
|
|
|
|
## Bugfixes and New Features
|
|
|
|
Before starting to write code, look for existing tickets or create one
|
|
in [Jira](https://jira.mongodb.org/browse/MOTOR) for your specific issue
|
|
or feature request.
|
|
|
|
## Running Tests
|
|
|
|
Install a recent version of MongoDB and run it on the default port from
|
|
a clean data directory. Pass "--setParameter enableTestCommands=1" to
|
|
mongod to enable testing MotorCursor's `max_time_ms` method.
|
|
|
|
Control how the tests connect to MongoDB with these environment
|
|
variables:
|
|
|
|
- `DB_IP`: Defaults to "localhost", can be a domain name or IP
|
|
- `DB_PORT`: Defaults to 27017
|
|
- `DB_USER`, `DB_PASSWORD`: To test with authentication, create an
|
|
admin user and set these environment variables to the username and
|
|
password
|
|
- `CERT_DIR`: Path with alternate client.pem and ca.pem for testing.
|
|
Otherwise the suite uses those in test/certificates/.
|
|
|
|
Install [tox](https://testrun.org/tox/) and run it from the command line
|
|
in the repository directory. You will need a variety of Python
|
|
interpreters installed. For a minimal test, ensure you have your desired
|
|
Python version on your path, and run:
|
|
|
|
```bash
|
|
tox -m test
|
|
```
|
|
|
|
The doctests pass with Python 3.10+ and a MongoDB 5.0 instance running on
|
|
port 27017:
|
|
|
|
```bash
|
|
tox -m doctest
|
|
```
|
|
|
|
## Running Linters
|
|
|
|
Motor uses [pre-commit](https://pypi.org/project/pre-commit/) for
|
|
managing linting of the codebase. `pre-commit` performs various checks
|
|
on all files in Motor and uses tools that help follow a consistent code
|
|
style within the codebase.
|
|
|
|
To set up `pre-commit` locally, run:
|
|
|
|
```bash
|
|
pip install pre-commit # or brew install pre-commit for global install.
|
|
pre-commit install
|
|
```
|
|
To run `pre-commit` manually, run:
|
|
|
|
```bash
|
|
tox -m lint
|
|
```
|
|
|
|
## General Guidelines
|
|
|
|
- Avoid backward breaking changes if at all possible.
|
|
- Write inline documentation for new classes and methods.
|
|
- Add yourself to doc/contributors.rst :)
|