Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
62 lines (41 loc) · 2.94 KB

CONTRIBUTING.md

File metadata and controls

62 lines (41 loc) · 2.94 KB
Raw

Contributing

Thank you for improving this project! We value small, precise changes that solve real problems. We value incremental, detail‑first contributions over big rewrites or abstractions.

1. Philosophy

"Nobody should start to undertake a large project. You start with a small trivial project, and you should never expect it to get large. If you do, you'll just overdesign and generally think it is more important than it likely is at that stage. Or worse, you might be scared away by the sheer size of the work you envision. So start small, and think about the details. Don't think about some big picture and fancy design. If it doesn't solve some fairly immediate need, it's almost certainly over-designed. And don't expect people to jump in and help you. That's not how these things work. You need to get something half-way useful first, and then others will say "hey, that almost works for me", and they'll get involved in the project." — Linus Torvalds

2. Code & Commit Conventions

  • Conventional Commits Follow https://www.conventionalcommits.org/en/v1.0.0/:

    • feat: … for new features
    • fix: … for bug fixes
    • chore: … for maintenance

  • Logical Commits Group changes by purpose. It’s okay to have multiple commits in a PR, but if they’re mere checkpoints, squash them into a single logical commit.

  • Lint & Tests Run existing linters/formatters and ensure all tests pass.

3. Pull Request Workflow

  • One logical change per PR.
  • Rebase or squash before opening to keep history concise.
  • Title & Description
    • Title uses Conventional Commits style.
    • Description explains what and why—keep context minimal.

4. Architecture Decision Records

When making a significant architectural decision, document it as an ADR in docs/adr/.

  • Copy docs/adr/template.md to docs/adr/NNN-short-title.md
  • Fill in Context (value-neutral facts), Decision (active voice), and Consequences (positive and negative)
  • Set status to Proposed in the PR, then Accepted once merged
  • Add a row to the index in docs/adr/README.md
  • ADRs are immutable once accepted — create a new one to supersede an existing decision

5. Issue Reporting

  • Search existing issues first.
  • Provide a minimal reproducible example and clear steps.

6. Automation & Checks

We enforce quality via CI on every push and PR:

  • Commitlint for commit‑message style
  • Linters/Formatters
  • Integration tests

Failures must be fixed before review.

7. Code of Conduct & Support

  • Please see CODE_OF_CONDUCT.md for behavioral expectations and reporting.
  • For quick questions or discussions, open an issue with the discussion label or mention a maintainer.

Thanks again for helping keep this project small, simple, and impactful!