Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
165 lines (98 loc) · 5.08 KB

CONTRIBUTING.md

File metadata and controls

165 lines (98 loc) · 5.08 KB
Raw

Contributing to pyochain

Thank you for your interest in contributing to pyochain!

This document covers environment setup, the commands to run, and how to commit and release.

For the architecture and coding conventions, see AGENTS.md. It is destined for any developer, wether human or machine.

Setup

This project uses uv to manage everything python-related.

After cloning the repo, copy the cargo config example to .cargo/config.toml (git-ignored) and adapt it to your platform to set-up the python path for PyO3.

Then you can sync the venv with uv.

--all-groups will also install the dependencies necessary for the website documentation, and the type-checking tests.

uv sync --dev
uv sync --all-groups

To set clippy and per-crate compilation settings for rust-analyzer, a zed and vscode config files are present.

Open for PR's for linux/mac cargo config examples, as well as others editors configs.

Usual workflow

The command you will run most often is the following, which will build the package in development mode and run the tests:

uv run maturin develop --uv;
uv run pytest

For benchmarks, you can run the following command:

uv run maturin develop --uv --profile profiling

See the readme for more informations.

linting/formatting/type checking

Before any pull request, or commit to the master branch, you need to ensure that all checks pass. Run the following command for more informations:

uv run -m scripts ci --help

Documentation

Stubs Docstrings

docstrings should follow the google format. See more information on Google Python Style Guide.

The code in the examples section will be automatically part of the test suite (pytest-docflex, which also collects README.md and docs/).

Every function in a stub needs a docstring with at least one closed python code block, this is checked by pyochain-build (see below).

We use code blocks instead of doctests, which means that the whole pytest ecosystem is available, which can be handy for expected failures.

See this file for a practical reference for documentation style.

Automatic generation

Prior to a release, run the tool to check the coherence between the stubs and the Rust source, generate the pages of docs/reference, and validate the navigation of zensical.toml.

A new class page must also be added to the nav of zensical.toml.

You can run one of the following commands:

cargo run -p pyochain-build
cargo run --release -p pyochain-build
cargo build -p pyochain-build
cargo build --release -p pyochain-build

Website build

To build and serve the documentation locally, run the command below.

Note that the -c flag is necessary, has zensical still has various issues with caching and will give inconsistent results with it.

uv run zensical build -c

Then open your browser with the site to view the generated documentation.

Contributing workflow

  • Create a branch per feature/fix and keep commits focused and descriptive.
  • Run all quality checks locally before opening a pull request.
  • Include tests or doctest examples for behavior changes whenever possible.
  • For Rust changes, consider adding benchmarks to verify performance impact when pertinent.

Each commit should be prefixed with one of the following tags:

  • enh => enhancement, improved typing, API documentation, etc...
  • fix => bug fix, logical error correction, typo, etc...
  • refactor => code refactoring, no functional change
  • feat => new feature
  • chore => maintenance task, CI, build, dev documentation, etc...
  • perf => performance improvement, no behavior change

Release process

Publishing a GitHub release triggers two workflows: publish.yml (Pypi package) and docs.yml (builds the website and deploys it to GitHub Pages).

The version to release is the one in pyproject.toml.

Changelogs and release template

Below is a template used for sections in CHANGELOG.md and release notes on GitHub.

When preparing a release, update the "unreleased" section with the relevant changes and then move it to a new section with the version number and release date.

# Pyochain v<VERSION>

## Changes

### 💥 Breaking changes

### 🏆 Highlights

### ⚠️ Deprecations

### 🆕 New features

### 🚀 Performance improvements

### ⚠️ Performance regressions

### ✨ Enhancements

### 🐞 Bug fixes

### 📖 Documentation

### 🛠️ Other improvements

### 🔄 Refactors

### 📦 Build system

### 🔗 Dependencies

### 🧪 Tests

Issue on release

If an issue on a release appear, AND the package is NOT published on Pypi, running the following commands can help going back to a clean state without needing to create a new release:

git tag -d <tag_name>
git push origin --delete <tag_name>

This will convert the last tag into a draft release, allowing you to fix the issue and publish the release again without creating a new one.