Contributing Guide

Contributions are welcome. This guide covers how to set up development environments, run tests, and format your code.

Gitflow Branching Model

Mongomock follows the standard Gitflow Workflow:

  • develop: The primary branch for integration. All feature pull requests must target develop and not master.
  • master: Holds stable, tagged release histories.
  • support/2.x: Legacy maintenance and bugfixes for the 2.x releases.

Setup local development environment

Mongomock uses Hatch for compilation, dependencies, and environment matrix configuration.

# 1. Clone the repository
$ git clone git@github.com:mongomock/mongomock.git
$ cd mongomock

# 2. Install Hatch globally
$ pipx install hatch

# 3. Execute unit tests across standard configurations
$ hatch test

Running Multi-Configuration Tests (Docker & Matrix)

You can run tests inside isolated environments alongside a physical MongoDB v5.0.5 container using Docker Compose:

$ docker compose build
$ docker compose run --rm mongomock

To test against a specific Python and PyMongo version combination in Docker:

$ docker compose run --rm mongomock hatch test -py=3.12 -i pymongo=4

Format and Lint

Mongomock strictly enforces style rules using ruff. Contributions must pass formatting validations before they can be merged. To format your code automatically:

$ hatch fmt

Running Static Type Checks

Validate type safety using MyPy:

$ hatch run types:check

The utcnow Rule

To ensure consistent time management and allow developers to simulate time offsets, never call datetime.utcnow() directly inside core modules. Always use the library helper method:

import mongomock

# Correct way to get the current timestamp
current_time = mongomock.utcnow()

This ensures that user tests can patch temporal states reliably.

Submitting a Pull Request

Before submitting a PR, verify that:

  1. Tests are included: You have written unit tests covering any new features or bug fixes. If applicable, test comparisons against a physical MongoDB engine inside your test files.
  2. No regressions: Existing test suites must pass successfully.
  3. Strictly Formatted: You ran hatch fmt to ensure conformity with project styling guidelines.
  4. Target Branch: Your PR is pointed at the develop branch.