Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
96 lines (60 loc) · 5.26 KB

CONTRIBUTING.md

File metadata and controls

96 lines (60 loc) · 5.26 KB
Raw

Contributing to django-paradedb

Welcome! We're excited that you're interested in contributing to django-paradedb and want to make the process as smooth as possible.

Technical Info

Before submitting a pull request, please review this document, which outlines what conventions to follow when submitting changes. If you have any questions not covered in this document, please reach out to us in the ParadeDB Community Slack or via email.

Selecting GitHub Issues

All external contributions should be associated with a GitHub issue. If there is no open issue for the bug or feature that you'd like to work on, please open one first. When selecting an issue to work on, we recommend focusing on issues labeled good first issue.

Ideal issues for external contributors include well-scoped, individual features as those are less likely to conflict with our general development process. We welcome documentation contributions that accompany a feature, correct wrong information, improve clarity, or fix typos.

Claiming GitHub Issues

This repository has a workflow to assign issues to new contributors automatically. This ensures that you don't need approval from a maintainer to pick an issue.

  1. Before claiming an issue, ensure that:

    • It's not already assigned to someone else.
    • There are no comments indicating ongoing work.

  2. To claim an unassigned issue, comment /take on the issue. This will automatically assign the issue to you.

If you find yourself unable to make progress, don't hesitate to seek help in the issue comments or the ParadeDB Community Slack. If you no longer wish to work on the issue(s) you self-assigned, please remove yourself from the Assignees list in the sidebar to release it.

Development Workflow

django-paradedb is a Python package that provides Django ORM integration for ParadeDB. Development is done with uv, which keeps Python selection and dependencies aligned between local work and CI.

# Clone the repository
git clone https://github.com/paradedb/django-paradedb.git
cd django-paradedb

# Install uv: https://docs.astral.sh/uv/getting-started/installation/

# Create or update the project environment
uv sync --extra dev

# Install prek hooks
uvx prek install

# Run tests
bash scripts/run_tests.sh

# Run linting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run mypy paradedb

# Run API/package consistency checks
uv run python scripts/check_api_coverage.py
uv run python scripts/check_api_stub_sync.py
bash scripts/smoke_wheel_install.sh

Pull Request Workflow

All changes to django-paradedb happen through GitHub Pull Requests. Here is the recommended flow for making a change:

  1. Before working on a change, please check if there is already a GitHub issue open for it.
  2. If there is not, please open an issue first. This gives the community visibility into your work and allows others to make suggestions and leave comments.
  3. Fork the django-paradedb repo and branch out from the main branch.
  4. Install prek hooks within your fork with uvx prek install to ensure code quality and consistency with upstream.
  5. Make your changes. If you've added new functionality, please add tests. We will not merge a feature without appropriate tests.
  6. Open a pull request towards the main branch. Ensure that all tests and checks pass. Note that the django-paradedb repository has pull request title linting in place and follows the Conventional Commits spec.
  7. Congratulations! Our team will review your pull request.

If your change touches SQL wrappers, API constants, packaging, or release metadata, run the API/package checks above before opening the PR.

Documentation

If you are adding a new feature that requires new documentation, please add the documentation as part of your pull request. Documentation can be added to:

  • The main README.md for user-facing features
  • Docstrings for API documentation
  • The examples/ directory for usage examples

We will not merge a feature without appropriate documentation.

Legal Info

Contributor License Agreement

In order for us, ParadeDB, Inc., to accept patches and other contributions from you, you need to adopt our ParadeDB Contributor License Agreement (the "CLA"). The current version of the CLA can be found on the CLA Assistant website.

ParadeDB uses a tool called CLA Assistant to help us track contributors' CLA status. CLA Assistant will automatically post a comment to your pull request indicating whether you have signed the CLA. If you have not signed the CLA, you must do so before we can accept your contribution. Signing the CLA is a one-time process for this repository, is valid for all future contributions to django-paradedb, and can be done in under a minute by signing in with your GitHub account.

If you have any questions about the CLA, please reach out to us in the ParadeDB Community Slack or via email at legal@paradedb.com.

License

By contributing to django-paradedb, you agree that your contributions will be licensed under the MIT License.