Lewati ke konten utama

Contributing

Contributing to Reflow

Review Checklist

Ubah satu release-workflow problem yang sudah dipahami menjadi focused change dengan safety evidence yang dapat diverifikasi.

Commandmake check

Category

Developer Guide

Quick Command

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

Overview​

Contribution untuk Reflow harus mempertahankan repository identity, explicit mutation scope, dry-run behavior, confirmation, dan actionable failure reporting. Jangan gabungkan unrelated cleanup, release metadata, version changes, atau publication dengan focused source change.

Contribution Workflow

Workflow Timeline

1
Telusuri affected flow
Ikuti CLI resolution melalui configuration, repository materialization, core behavior, presentation, dan external boundaries.
completed
2
Tentukan safety contract
Nyatakan target, effects, dry-run behavior, confirmation, compatibility, dan failure outcomes sebelum mengedit.
completed
3
Implementasikan bersama tests
Pisahkan responsibilities dan tambahkan focused coverage untuk success, failure, dan non-mutating behavior.
current
4
Jalankan widening validation
Jalankan focused tests, pre-commit checks, make check, dan workflow validation yang berlaku.
pending
5
Sinkronkan documentation
Update commands, configuration, safety, troubleshooting, architecture, dan examples ketika contract berubah.
pending
6
Siapkan handoff
Laporkan files, decisions, commands, outcomes, limitations, dan hal yang sengaja tidak diubah.
pending

Branch and Scope Conventions

Suggested Branch Types

Feature

Gunakan feature/<name> untuk focused capability.

Bug Fix

Gunakan bugfix/<name> untuk focused correction.

Release

Gunakan release/<version> hanya untuk intentional release preparation.

Primary Development

Perlakukan main dan develop sebagai long-lived project branches.

Jangan commit, tag, push, rewrite history, publish packages atau images, replay tags, maupun mengubah release metadata hanya karena source validation berhasil.

Implementation Standards

Before You Begin

  • Pertahankan focused layersRequired

    CLI interaction tetap berada di app/cli; reusable behavior berada di app/core atau service yang sesuai.

  • Pertahankan repository identityRequired

    Jangan mengganti selected target repository dengan Reflow source checkout atau registry image.

  • Lindungi dry-runRequired

    Setiap mutating path memerlukan bukti bahwa dry-run tidak menghasilkan persistent local atau external change.

  • Tangani errors satu kaliRequired

    Tampilkan remediation ringkas pada CLI boundary dan sembunyikan sensitive atau deep diagnostics dari normal output.

  • Dokumentasikan public contractsRequired

    Sinkronkan command, option, configuration, safety, migration, dan 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 tetap coherentRequired

    Setiap changed file mendukung behavior, tests, atau documentation yang dinyatakan.

  • Target dan effects bersifat explicitRequired

    Local paths, remote URLs, registries, confirmation, dan dry-run behavior tetap predictable.

  • Tests tetap isolatedRequired

    Tests menggunakan temporary repositories, mocks, dan deterministic configuration, bukan personal state atau credentials.

  • Quality checks dilaporkanRequired

    Formatting, lint, tests, dan relevant builds memiliki explicit outcomes.

  • Tidak ada unapproved release actionRequired

    Versions, changelogs, tags, pushes, releases, dan publication tidak berubah kecuali sudah disetujui dalam scope.

Related Commands

Commands commonly used together with this command.

Testing

Pilih focused dan complete validation.

Dry Run

Lindungi non-mutating workflow guarantees.