Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
93 lines (66 loc) · 3.69 KB

CONTRIBUTING.md

File metadata and controls

93 lines (66 loc) · 3.69 KB

Contributing to PR Maven CLI

Thank you for considering a contribution.

PR Maven CLI is intentionally designed as a contributor-friendly OSS project. The roadmap is split into focused issues so humans and automated coding agents can make useful progress without needing deep project context.

Baseline

  • Language: Go.
  • Runtime dependencies: none for the stage 1 core.
  • Target Maven baseline: Maven 3.9.x, documented against Maven 3.9.16.
  • Maven 4 support is planned after the Maven 4 line is production-ready.
  • License: Apache-2.0.

Setup

git clone https://github.com/pr-cli/pr-maven-cli.git
cd pr-maven-cli
go test ./...

Run the demo:

go run ./cmd/prmaven fails -project demo/multi-module-failure
go run ./cmd/prmaven why -project demo/multi-module-failure -format json

The demo includes versioned Maven report fixtures under demo/multi-module-failure/**/target/*-reports.

For the full test strategy, including golden files, CLI end-to-end tests, race tests, and CI behavior, read docs/testing.md.

For the GitHub pipeline, release flow, and branch protection recommendation, read docs/ci.md and docs/release.md.

For issue and pull request taxonomy, read docs/labels.md. For maintainer-facing labeling workflow and scoped issue examples, read docs/maintainer-labeling.md. Every planned issue and pull request should be labeled so contributors can understand type, area, stage, and readiness.

Every new issue and pull request receives the standard contributor thank-you message from .github/contributor-thanks.md. The automation lives in .github/workflows/thank-contributor.yml.

Contribution Rules

  • Keep PRs focused.
  • Include tests for behavior changes.
  • Preserve stable JSON fields unless the issue explicitly allows a breaking change.
  • Prefer deterministic parsing over guessing.
  • Keep network access optional.
  • Do not add telemetry.
  • Do not require external services for core tests.
  • Do not commit generated binaries, local caches, or private CI logs.
  • Keep branch names, pull request titles, commit messages, and merge messages focused on the product change. Do not include coding agent or tool names such as codex, claude, gemini, copilot, cursor, windsurf, aider, or devin.

Good First Contributions

Good first issues usually fit one of these areas:

  • Add a parser fixture for a Maven plugin report.
  • Improve output wording.
  • Add edge-case coverage for Maven module discovery.
  • Add documentation examples.
  • Add one JSON field with a clear acceptance test.
  • Improve error messages.

Pull Request Checklist

  • The PR solves one issue or one clearly scoped problem.
  • go test ./... passes.
  • Golden files are updated when human-readable output intentionally changes.
  • New behavior is covered by tests or fixtures.
  • Documentation is updated when user-facing behavior changes.
  • JSON output compatibility is preserved or the breaking change is explicitly justified.

Automated Contributions

Automated coding agents are welcome when the contribution is reviewable.

Expected standard:

  • The PR title references the issue.
  • The PR body explains the change in plain language.
  • Tests are included.
  • The diff is scoped.
  • The contribution does not perform unrelated refactors.
  • Public metadata describes the product change, not the automation used to produce it.

Maintainers

Maintainers are expected to:

  • Keep issues small and actionable.
  • Add acceptance criteria to issues.
  • Label issues consistently.
  • Review contributor PRs with clear, respectful feedback.
  • Favor production reliability over feature volume.