Contributing

Contributions are welcome, and they are greatly appreciated! Every little helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs to our issue page. If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation

coodie could always use more documentation, whether as part of the official coodie docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback our issue page on GitHub. If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome 😊

Get Started!

Ready to contribute? Here’s how to set yourself up for local development.

Prerequisites

Python 3.10+
uv (recommended) or pip
Docker (for integration tests)

Quick Setup

# Fork & clone
git clone git@github.com:your_name_here/coodie.git
cd coodie

# Install dependencies with uv (recommended)
uv sync --all-extras

# Install bats for workflow shell script tests (optional)
# macOS:  brew install bats-core
# Ubuntu: sudo apt-get install bats
# Or from source: https://bats-core.readthedocs.io/en/stable/installation.html

# Or with pip
pip install -e ".[scylla]"
pip install pytest pytest-cov pytest-asyncio pre-commit

# Install pre-commit hooks
uv run pre-commit install

# Run unit tests (no database needed)
uv run pytest tests/ -v

# Run linters
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Lint GitHub Actions workflows
# (requires actionlint: https://github.com/rhysd/actionlint)
actionlint

# Or run all pre-commit hooks at once (includes actionlint)
uv run pre-commit run --all-files

Running Integration Tests

Integration tests need a running ScyllaDB instance. The test suite uses testcontainers to start one automatically:

# Run integration tests (starts ScyllaDB via Docker)
uv run pytest tests/ -v -m integration

Creating a Branch

git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.

Committing

Commit messages must follow Conventional Commits:

git add .
git commit -m "feat(something): your detailed description of your changes"
git push origin name-of-your-bugfix-or-feature

Examples:

feat(aio): add TTL support to Document.save()
fix(cql_builder): escape column names with reserved words
docs: update quickstart guide
test(sync): add QuerySet chaining coverage

We run commitlint on CI to validate commit messages. If you’ve installed pre-commit hooks, the message will be checked at commit time.

Submitting a Pull Request

Submit a pull request through the GitHub website or using the GitHub CLI:

gh pr create --fill

Pull Request Guidelines

We like to have the pull request open as soon as possible, that’s a great place to discuss any piece of work, even unfinished. You can use draft pull request if it’s still a work in progress. Here are a few guidelines to follow:

Include tests for feature or bug fixes.
Update the documentation for significant features.
Ensure tests are passing on CI.

Plan-Linking Convention

If your PR implements a phase of a multi-phase plan in docs/plans/, you can link the PR to the plan so the Plan Phase Continuation workflow automatically delegates the next phase to Copilot after merge.

Add one or both of these lines to your PR body:

Plan: docs/plans/<plan-name>.md
Phase: N

Plan: — path to the plan file (case-insensitive, relative to repo root)
Phase: — the phase number this PR completes (optional; if omitted the workflow detects the completed phase from the plan’s own ✅ markers)

Example PR body:

Implements phase 2 of the UDT support plan.

Plan: docs/plans/udt-support.md
Phase: 2

As a fallback the workflow also detects the plan from the branch name if it follows the convention plan/<plan-name>/phase-N (e.g. plan/udt-support/phase-2).

When a PR introduces a new plan file (adds a docs/plans/*.md file), the workflow treats the merge as the bootstrap trigger and automatically starts Phase 1 — no explicit Plan: line is needed.

Tips

To run a subset of tests:

uv run pytest tests/ -k "test_something" -v

Workflow Testing

The repository’s GitHub Actions workflows are tested at three levels:

Static Analysis — actionlint runs via pre-commit (which CI also runs) to catch YAML and expression errors.
Shell Script Unit Tests — Complex shell logic is extracted into .github/scripts/ and tested with Bats. A custom pytest-bats plugin (tests/workflows/conftest.py) collects .bats files as pytest items, so they run alongside regular Python tests:
```
# Direct (requires bats installed)
bats tests/workflows/

# Via pytest (the conftest.py plugin runs each @test block as a pytest item;
# skips gracefully if bats is not installed)
uv run pytest tests/workflows/ -v
```
Convention Checks — tests/test_workflow_conventions.py enforces project-level rules (pinned actions, concurrency groups, GH_TOKEN, etc.) via pytest.

Manual Smoke Tests (workflow_dispatch)

The Plan Phase Continuation workflow supports a workflow_dispatch trigger for manual testing:

Go to Actions → select the workflow → Run workflow.
Enter the plan file path (e.g. docs/plans/udt-support.md) and optionally the completed phase number.
Verify the expected comment is posted on the PR.

Making a new release

Releases happen automatically when commits are merged to master. The CI workflow uses python-semantic-release to analyse Conventional Commits and determine whether a version bump is needed:

Commit prefix	Version bump
`fix:`	Patch (`0.0.x`)
`feat:`	Minor (`0.x.0`)
`feat!:` / `BREAKING CHANGE:`	Major (`x.0.0`)

When a new version is detected the CI will:

Update CHANGELOG.md and push a version tag (e.g. v1.0.0).
Create a GitHub Release with auto-generated release notes.
Build the package with uv build (version derived from the tag via hatch-vcs).
Publish to PyPI using Trusted Publishing (OIDC).

No manual tagging or PyPI token management is required.

Setting up Trusted Publishing on PyPI

Trusted Publishing lets PyPI verify GitHub Actions runs via OpenID Connect (OIDC), so you never have to create or rotate a PyPI API token.

One-time setup steps (done once per PyPI project):

Go to https://pypi.org and log in.
Open the project page for coodie, then go to Manage → Publishing.
- If the project does not exist yet, go to https://pypi.org/manage/account/publishing/ to add a pending publisher before the first upload.
Click Add a new publisher and fill in the form:

Field

Value

Owner

scylladb

Repository name

coodie

Workflow name

ci.yml

Environment name

release
Click Add.

GitHub repository setup:

In the repository, go to Settings → Environments and create an environment named release.
Optionally add protection rules (e.g. require a reviewer before the publish job runs).

Once this is done, every merge to master that includes a feat: or fix: commit will trigger an automatic release and PyPI publish — no stored credentials needed.

Field	Value
Owner	`scylladb`
Repository name	`coodie`
Workflow name	`ci.yml`
Environment name	`release`