Skip to content

Contributing to rowsmyth

Thank you for your interest in contributing!

Prerequisites

  • Python 3.12+
  • Java 17+ with java on your PATH (or JAVA_HOME set) for PySpark integration tests
  • uv - package manager

PySpark 4.x requires a JDK; CI installs Temurin 17 automatically. Set JAVA_HOME or add java to your PATH before running make test.

Setup

git clone https://github.com/LaurenceRawlings/rowsmyth.git
cd rowsmyth
make install

make install runs uv sync --all-groups, including the spark dependency group (pyspark) used for integration tests. PySpark is not a core runtime dependency so published installs do not override cluster-provided versions.

Pull requests

PRs are merged via squash merge - the PR title becomes the single commit on main. Keep each PR focused on one type of change so cz bump can determine the correct version bump from the commit history.

PR title format: type(optional-scope): short description

Example: feat: add ... to ...

See the PR template for the full type reference and version bump rules.

Commit convention

This project uses Conventional Commits. The commit-msg hook enforces this on local commits automatically.

Commits within a branch are squashed on merge, so local commit messages are flexible - what matters is the PR title.

Type Version bump When to use
feat minor New user-visible feature
fix patch Bug fix
feat! / fix! major Breaking change (append !)
docs none Documentation only
style none Formatting, whitespace - no logic change
refactor none No functional change
test none Tests only
perf patch Performance improvement
build none Build system or dependency changes
ci none CI/CD configuration changes
chore none Maintenance not covered by other types
revert patch Reverts a previous commit

Running checks

make test        # tests only
make lint        # ruff check --fix
make format      # ruff format
make typecheck   # ty strict mode
make security    # bandit scan
make pre-commit  # run all pre-commit hooks on all files
make ci          # run the full local CI suite

Adding tests

All PRs must maintain 100% test coverage. If you add or change code, add tests that cover it through the public API. Docstring examples in src/ are collected by the default pytest command.

Spark integration tests use chispa for DataFrame assertions (assert_df_equality, assert_column_equality, etc.).

Understanding the codebase

See docs/design.md for the product design and API behaviour.

Source layout:

  • src/rowsmyth/model.py - declarative Model base, variant decorator
  • src/rowsmyth/factory.py - fluent Factory and create()
  • src/rowsmyth/dataset.py - Dataset, RowCtx, active dataset context
  • src/rowsmyth/resolution.py - FK resolution and validation
  • src/rowsmyth/pool.py - Pool and deferred pool tokens
  • src/rowsmyth/errors.py - rowsmyth exception hierarchy

Releasing (maintainers only)

cz bump
git push
git push --tags

cz bump reads the commit history, determines the next SemVer, updates CHANGELOG.md and creates a bump commit + vX.Y.Z tag. The CD workflow on GitHub Actions handles the rest.