Contributing

🚀Contributing

Review Checklist

Turn one understood problem into a focused change with evidence that reviewers can verify.

Commandmake check

📦Category

Developer Guide

🚀Quick Command

scope -> implement -> validate -> document -> hand off

---

qualitytestsdocumentationreview

---

🌿

Primary Branches

main and develop

🧪

Quality Helper

make check

📄

Source Standard

Typed and documented

🛡️

Change Style

Focused

Overview

A useful Custy contribution explains the behavior being changed, keeps CLI and core responsibilities separated, adds evidence at the right test layers, and updates user or developer documentation whenever the public contract changes.

💡Reviewability is part of quality

Small, coherent changes are easier to test, reason about, and recover. Avoid mixing formatting, unrelated cleanup, behavior changes, version bumps, and release artifacts into one contribution.

---

Contribution Workflow

🕒Workflow Timeline

1

Understand the affected flow

Trace the active CLI entry point, configuration, core behavior, side effects, and existing tests before editing.

completed

2

Define a focused contract

State inputs, outputs, errors, side effects, compatibility expectations, and the smallest set of affected files.

completed

3

Implement with tests

Keep responsibilities separated, document non-obvious interfaces, and add focused coverage alongside behavior.

current

4

Run widening validation

Run the affected tests, integration or regression coverage, then formatting, lint, and the complete suite.

pending

5

Update documentation

Synchronize command, configuration, workflow, architecture, developer, and troubleshooting guidance as applicable.

pending

6

Prepare the handoff

Summarize changed files, decisions, validation results, known limits, and anything intentionally left unchanged.

pending

---

Branch and Scope Conventions

✨Repository Branch Types

✨Feature

Use feature/<name> for a focused new capability.

⚠️Bug Fix

Use bugfix/<name> for a focused correction.

🏷️Release

Use release/<version> only for an intentional release-preparation change.

🌿Primary Development

Treat main and develop as the repository's primary long-lived branches.

Follow the repository owner's current workflow when it differs from these defaults. Do not rewrite shared history, publish a tag, bump a version, generate a changelog, or push a branch merely because a source change is complete.

---

Implementation Standards

📌Before You Begin

• Keep boundaries clearRequired

  Typer and presentation stay in app/cli; reusable workflow and domain behavior stay in app/core or another focused active package.

• Use useful typesRequired

  Type public and non-obvious values and prefer explicit dataclasses or enums where they clarify a contract.

• Document behaviorRequired

  Add accurate module, class, function, and method documentation, including real arguments, returns, errors, side effects, and examples when useful.

• Log deliberatelyRequired

  Use actionable levels and context without secrets, raw credentials, tokens, or duplicate noise.

• Keep functions focusedRequired

  Prefer readable composition and small responsibilities over clever or unnecessary abstractions.

• Preserve user safetyRequired

  Use clear errors, safe defaults, predictable prompts, dry-run support where applicable, and explicit confirmation for consequential behavior.

---

Quality Gates

Start with the focused commands described in Testing, then run the complete checks from the active venv/ environment.

Contributor validation

bash

# Focused example
python -m pytest tests/core/pipeline

# Full tests with configured coverage

python -m pytest

# Formatting check, Ruff lint, and full tests

make check

# Validate the hook configuration

make pre-commit-validate

# Check staged files during normal contributor work

make pre-commit-run-staged

# Check every tracked file before handoff

make pre-commit-run

If a check cannot run, report the command, environment limitation, and the validation that did run. Do not describe an unexecuted or failing check as passing.

⚠️Refresh is a maintainer operation

Run make pre-commit-refresh only when intentionally upgrading hook revisions. It updates .pre-commit-config.yaml, rebuilds hook environments, reinstalls the Git hook, and runs all hooks against all files. It can require network access and modify active source files, so review its complete diff before committing.

---

Documentation Responsibilities

Update documentation when a contribution adds or changes commands, options, configuration, workflows, profiles, side effects, architecture, extension points, errors, requirements, or recovery steps. Keep examples executable and distinguish stable public behavior from internal, experimental, loaded-only, reserved, or mismatched behavior.

Use the existing Docusaurus component language for consistent navigation and scanning. Reuse components before adding a new one, provide meaningful image alternative text, and validate MDX routes and internal links with the site build.

---

Final Review Checklist

📌Before You Begin

• Scope is focusedRequired

  Every changed file supports the stated behavior, tests, or documentation.

• Public behavior is intentionalRequired

  CLI paths, options, defaults, prompts, errors, and side effects match the agreed contract.

• Tests cover the riskRequired

  Focused, integration, and regression coverage address successful and failing paths at the right boundaries.

• Quality checks are reportedRequired

  Formatting, lint, tests, and relevant builds have explicit outcomes.

• Documentation is synchronizedRequired

  Users and contributors can understand requirements, behavior, safety, and recovery.

• No unrelated release action occurredRequired

  Versions, changelogs, tags, pushes, and publication remain untouched unless they were explicitly part of the work.

---

🛡️Never weaken tests to hide a defect

Change a test when the intended contract changes and explain why. Do not remove assertions, skip coverage, or delete tests only to make the suite pass.

---

Continue

🚀Related Commands

Commands commonly used together with this command.

Development Setup

Create the supported editable environment.

Testing

Select focused and complete validation.

Adding Commands

Preserve the active CLI module boundaries.

Adding Pipeline Steps

Preserve registration, priority, composition, and failure contracts.