Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
121 lines (89 loc) · 4.98 KB

CONTRIBUTING.md

File metadata and controls

121 lines (89 loc) · 4.98 KB
Raw

Contributing to pinto

Thanks for considering a contribution. pinto is deliberately small: every change should support practical Scrum work while preserving a fast, local-first, plain-text tool.

Read AGENTS.base.md and docs/DESIGN.md before making design decisions.

For a new command, backend, or report, record the Scrum-related need, why existing functionality is insufficient, and the dependency, persistence, and migration/compatibility impact in the issue or pull request. Keep the file and Git backends as the plain-text default; consult stability decisions for SQLite changes.

AGENTS.base.md is the shared contributor and agent baseline. Developers who need personal tool or environment instructions may create a local AGENTS.md overlay with cp AGENTS.base.md AGENTS.md, then append those instructions without changing the shared file. Root-level AGENTS.md, CLAUDE.md, and .claude/ are ignored and must not be committed; durable project guidance belongs in the tracked baseline or the linked documentation.

Project principles

  1. Lightweight and simple — fast startup, few dependencies, low learning cost.
  2. Scrum-focused — Product Backlog, Sprints, and Kanban are the core scope.
  3. Plain text and Git-friendly — data must stay readable and reviewable.
  4. Local first — no server, cloud synchronization, or account requirement.

Avoid turning pinto into a general project-management suite. Features unrelated to Scrum execution do not belong here.

Language

Use English for all natural-language content: documentation, code comments, commit messages, pull requests, issues, and UI/CLI fallback text (the default locale before localization). Localized user-facing messages (e.g. Fluent .ftl files) are the exception and may be written in their target language.

Set up the development environment

mise manages the toolchain and project tasks:

mise install

TDD is required

Follow Red → Green → Refactor for every behavior change:

  1. Write a failing test.
  2. Add the smallest implementation that makes it pass.
  3. Refactor only while the test suite remains green.

Keep domain behavior unit-testable under src/, and cover CLI input/output with integration tests in tests/. A commit should normally contain both the test and its implementation.

Before opening a pull request

Run the full gate:

mise run check

This runs tests, Clippy with warnings denied, Rust API documentation, the mdBook build, and formatting checks. The same command is used in CI. Update any affected documentation, keep error messages actionable, and avoid unwrap() or expect() on production paths.

See Testing and fuzzing for the reproducible public API doctest, CLI/PTTY smoke-test, and weekly libFuzzer workflow.

Toolchain and package reproducibility are documented in Reproducible builds and releases. The development and release toolchain is pinned by mise.toml; the committed Cargo.lock must be honored with --locked for source installs, checks, and release packaging.

Commit and maintainer review workflow

Keep changes in small, green commits: each commit should build and pass the focused tests that cover it. For cross-cutting work, separate data, service, CLI, and documentation changes where practical. If a change cannot be split without obscuring the behavior, explain the boundary in the pull request.

Before starting a large change, review its acceptance conditions and record the decisions that affect scope, persistence, migration, or release behavior. A destructive or release-related change must include its risk, verification, and recovery steps in the pull request. The primary maintainer records the final decision and any follow-up actions, then runs the strongest applicable checks. This documented fallback preserves traceability and keeps the change reviewable when maintainer capacity is limited.

Security work follows the security policy. The security maintainer owns private intake and coordinated disclosure, while the release maintainer owns versioning, changelog, package, tag, and publication checks. When responsibilities overlap, record the owner of each decision in the security or release record.

Backlog

pinto dogfoods its own board in .pinto/; it is the single source of truth for project work. Inspect it with cargo run -- list or cargo run -- board. The former repository-level backlog is not maintained; see docs/migration.md for historical context.

Pull request flow

  1. Fork the repository and create a focused branch.
  2. Implement the change through TDD.
  3. Run mise run check.
  4. Update the relevant documentation.
  5. Open a PR following the repository template.

Code of conduct and license

All participants must follow the Code of Conduct. By contributing, you agree to license your contribution under the MIT License.