clacky-ai--openclacky/CONTRIBUTING.md

Contributing to OpenClacky

Thanks for taking the time to contribute. Every PR will be reviewed. We evaluate each contribution along three dimensions:

1. Value of the need — is this useful, and to whom?
2. Architectural impact — does it fit the existing design?
3. Code standards — does it meet our quality bar?

Read the sections below before opening a PR. If your contribution clearly delivers outsized value, the rules here can bend — see Exceptions.

---

1. Architecture First

Improvements built on top of the existing, stable architecture are accepted quickly. By "stable architecture" we mean a change that:

• Solves the need with the smallest possible diff.
• Adds no new configuration knobs unless strictly required.
• Adds no new dependencies unless strictly required (see also §3).
• Respects the existing design intent — same layering, same abstractions, same naming conventions.
• Ideally simplifies the architecture rather than expanding it.

PRs that introduce parallel mechanisms, speculative abstractions, or "just in case" flexibility will be sent back for trimming.

2. Needs Should Be Shared and Side-Effect-Free

We prefer changes that benefit most users and have no side effects on others.

• Common needs (broadly applicable, opt-in by nature, isolated blast radius) → fast track.
• Niche needs (valuable to a few, but with potential to affect others' workflows, performance, or defaults) → reviewed more cautiously. Expect questions about scope, defaults, and rollout.

If your change alters existing default behavior, call it out explicitly in the PR description.

3. Code Standards

Tests

• All tests must pass before a PR can be merged.
• Coverage must not drop. New code needs new tests.

Commits & PRs

• Write commit messages and PR titles/descriptions in English. This applies to everyone, regardless of working language.
• Keep commits focused; squash noise before requesting review.
• PR descriptions should briefly state: what, why, and any user-visible impact.

Built with OpenClacky

• PRs authored using OpenClacky itself are prioritized for review and merge. Mention it in the PR description if applicable. We dogfood our own tool.

Dependencies

• Avoid adding new libraries. Prefer the standard library, existing dependencies, or a few lines of code over pulling in another gem/package.
• If a new dependency is genuinely necessary, justify it in the PR description: why this library, why not write it ourselves, license, maintenance status.

Style

• Follow the conventions already present in the file you're editing.
• See each sub-project's .clackyrules for project-specific rules (openclacky/, platform/, installer/).

---

Exceptions

Rules exist to keep the project healthy, not to block valuable work. For contributions that deliver substantial, clear value, the standards above can be relaxed at the maintainers' discretion. When in doubt, open an issue or draft PR first to discuss the trade-offs.

---

Code of Conduct

Participation in this project is governed by the Code of Conduct. By contributing, you agree to uphold it.