Contributing

Thanks for helping us make Bitmapist work better! Contributions are welcome, whether it's reporting an issue, submitting a pull request, or improving documentation.

Feel free to report any issue you may have.

Working on your first Pull Request? You can learn how from this free series: How to Contribute to an Open Source Project on GitHub.

Setting Up the Development Environment

We use uv for dependency management and pre-commit for code quality.

  1. Clone the repository: 

    git clone https://github.com/Doist/bitmapist.git
cd bitmapist

  2. Install uv: Follow the official uv installation instructions.

  3. Create a virtual environment and install dependencies: This command will install all production and development dependencies listed in pyproject.toml. 

    uv sync --all-extras --dev

  4. Install pre-commit hooks: This will run linters and formatters before each commit to ensure code consistency. 

    uv run pre-commit install

Running Tests

Our test suite uses pytest and requires a running Redis server.

  1. Ensure Redis is installed and running. The test suite will attempt to start its own Redis instance. You can control this with environment variables:

    • BITMAPIST_REDIS_SERVER_PATH: Path to the redis-server executable (defaults to one found in PATH or /usr/bin/redis-server).
    • BITMAPIST_REDIS_PORT: Port for the test Redis server (defaults to 6399).

  2. Run the test suite: 

    uv run pytest

Submitting Changes

When you are ready to contribute code, please open a Pull Request. Keep the following in mind:

  • The project is released under the BSD-3-Clause license.
  • Please add tests for your changes! All new features should be accompanied by tests.
  • Please document any user-facing changes using the Keep a Changelog convention. Changes in a PR should be documented under an [Unreleased] version.

Releasing New Versions

This process is handled by maintainers.

  1. Bump the version in pyproject.toml using uv: 

    uv version --bump minor

  2. Update the CHANGELOG with the release date and summary of changes.

  3. Commit the changes with the message Version X.X.X: 

    git commit -m "Version $(uv version --short)"

  4. Tag the commit with vX.X.X: 

    git tag -a -m "Release $(uv version --short)" "v$(uv version --short)"

  5. Push the commit and tags to the main branch.

  6. Create a new release on GitHub named vX.X.X based on the new tag.
  7. The GitHub Actions workflow will automatically build and publish the new version to PyPI.