Skip to main content

Contributing

Contributing to Reflow

Review Checklist

Turn one understood release-workflow problem into a focused change with verifiable safety evidence.

Commandmake check

Category

Developer Guide

Quick Command

scope -> implement -> validate -> document -> hand off
qualitytestsdry-rundocumentationpre-commit
Primary Branches
main and develop
Quality Helper
make check
Runtime
Python 3.14+
Mutation Policy
Explicit approval

Overview​

A Reflow contribution must preserve repository identity, explicit mutation scope, dry-run behavior, confirmation, and actionable failure reporting. Keep unrelated cleanup, release metadata, version changes, and publication out of a focused source change.

Contribution Workflow

Workflow Timeline

1
Trace the affected flow
Follow CLI resolution through configuration, repository materialization, core behavior, presentation, and external boundaries.
completed
2
Define the safety contract
State targets, effects, dry-run behavior, confirmation, compatibility, and failure outcomes before editing.
completed
3
Implement with tests
Keep responsibilities separated and add focused successful, failing, and non-mutating coverage.
current
4
Run widening validation
Run focused tests, pre-commit checks, make check, and applicable workflow validation.
pending
5
Synchronize documentation
Update commands, configuration, safety, troubleshooting, architecture, and examples when their contracts change.
pending
6
Prepare the handoff
Report files, decisions, commands, outcomes, limits, and anything intentionally unchanged.
pending

Branch and Scope Conventions

Suggested Branch Types

Feature

Use feature/<name> for a focused capability.

Bug Fix

Use bugfix/<name> for a focused correction.

Release

Use release/<version> only for intentional release preparation.

Primary Development

Treat main and develop as the long-lived project branches.

Do not commit, tag, push, rewrite history, publish packages or images, replay tags, or modify release metadata merely because source validation passed.

Implementation Standards

Before You Begin

  • Keep layers focusedRequired

    CLI interaction stays under app/cli; reusable behavior belongs in app/core or the appropriate service.

  • Preserve repository identityRequired

    Never substitute Reflow's source checkout or a registry image for the selected target repository.

  • Protect dry-runRequired

    Every mutating path requires evidence that dry-run performs no persistent local or external change.

  • Handle errors onceRequired

    Present concise remediation at the CLI boundary and keep sensitive or deep diagnostics out of normal output.

  • Document public contractsRequired

    Synchronize command, option, configuration, safety, migration, and architecture guidance.

Quality Gates

Contributor validation
bash
# Focused example
python -m pytest tests/cli/test_repository_targeting.py

# Complete tests and quality checks

python -m pytest
make check

# Hook configuration and tracked-file checks

make pre-commit-validate
make pre-commit-run-staged
make pre-commit-run

Final Review Checklist

Before You Begin

  • Scope is coherentRequired

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

  • Targets and effects are explicitRequired

    Local paths, remote URLs, registries, confirmation, and dry-run behavior remain predictable.

  • Tests are isolatedRequired

    Tests use temporary repositories, mocks, and deterministic configuration instead of personal state or credentials.

  • Quality checks are reportedRequired

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

  • No unapproved release action occurredRequired

    Versions, changelogs, tags, pushes, releases, and publication remain untouched unless explicitly scoped.

Related Commands

Commands commonly used together with this command.

Testing

Choose focused and complete validation.

Dry Run

Protect non-mutating workflow guarantees.