Contributor Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CLAUDE.md
• cubic.yaml
• lib/mutineer/reporter.rb
• rake/docs_contract.rb
• rake/site_build.rb
• rake/site_docs.rb
• rake/yard_pages.rb
• action.yml

Contributor guidelines define the technical standards and workflows for developing the Mutineer gem, GitHub Action, and associated documentation. The project prioritizes zero runtime dependencies, technical transparency, and strict contract stability for both CLI outputs and machine-readable reports.

AGENTS.md serves as the single source of truth for all development conventions and release procedures.

Technical Principles

Contributors must adhere to core architectural constraints to maintain the project's "clean-room" status and operational reliability.

Non-Negotiables

• Zero Runtime Dependencies: The gem uses only Prism and the Ruby standard library. You must never add runtime gems; development-only dependencies (Minitest, Rake, YARD) are permitted.
• Ruby Version Support: The project supports Ruby 3.4 and higher, as Prism ships with the core library in these versions.
• No eval Usage: You must not use eval. The project utilizes a redefine strategy that loads temporary file snippets to avoid supply-chain scanner flags.
• Score Discipline: The mutation score calculation follows a strict formula: killed / (killed + survived). You must exclude no_coverage, uncapturable, unplaceable, ran_at_load, ignored, skipped, and errored from the denominator.

Sources: AGENTS.md:7-14, AGENTS.md:118-120, lib/mutineer/reporter.rb:142-150

Local Development Workflow

Before committing changes, you must execute the local gate to ensure code quality and technical compliance.

Mandatory Pre-Commit Checks

1. Run the zero-dependency test suite: bundle exec rake test.
2. Perform a load smoke test: ruby -Ilib -e 'require "mutineer"'.
3. Verify documentation coverage: bundle exec rake yard:strict. This requires 100% documentation for all methods, constants, and private members.

This diagram illustrates the sequence of checks required to pass the local development gate. Sources: AGENTS.md:16-29

Specialized Testing Environments

• Minitest Compatibility: For changes affecting Minitest integration, you must also run tests using Minitest 6 via BUNDLE_GEMFILE=gemfiles/minitest6.gemfile bundle exec rake test.
• Rails Integration: Rails-dependent tests must be run via bundle exec rake test:daemon. The primary suite remains Rails-free.
• Website and Documentation: If you modify the GitHub Pages site, you must build the site (bundle exec rake site:build) and run Node.js tests (node --test test/site_test.js) and Playwright browser tests.

Sources: AGENTS.md:31-51

Code Review and Architecture Criteria

Reviewers and contributors focus on three high-priority areas during the pull request process: stability, honesty, and safety.

Category	Priority	Description
CLI Stability	Critical	Ensure exit codes, flags, and JSON report shapes remain stable.
Mutation Honesty	Critical	Flag code that silently skips mutants, weakens thresholds, or hides survivors.
Public API	High	Treat CHANGELOG, README, and docs/fragments as part of the public API.
Security	High	Prevent unsafe shell interpolation and path traversal in file handling or CI Action inputs.

Sources: cubic.yaml:14-23, cubic.yaml:45-60

Release Management

Mutineer uses a tag-driven release flow. CI handles publishing to RubyGems; you do not perform manual gem push operations.

Release Procedure

1. Version Bump: Update lib/mutineer/version.rb.
2. Changelog: Move the ## [Unreleased] block in CHANGELOG.md to a dated section.
3. Merge: Merge the branch into main.
4. Tag: Create and push a tag: git tag vX.Y.Z && git push origin vX.Y.Z.

The release automation ensures that published gems match the repository state and correctly updates GitHub Action tags. Sources: AGENTS.md:70-82

Automation and Safety

• Trusted Publishing: The project uses OIDC for RubyGems publishing, removing the need for API keys or OTP in CI.
• Release PRs: A weekly automation (release-pr.yml) opens a PR if unreleased feat: or fix: commits exist on main.
• Major Version Bumps: Behavior changes to GitHub Action defaults require a major version bump to prevent breaking users pinning @v1.

Sources: AGENTS.md:84-110, action.yml:85-98

Documentation Maintenance

Documentation is generated from a central contract to prevent drift between human-readable pages and machine-readable schemas.

• Docs Contract: The DocsContract module in rake/docs_contract.rb manages exit codes and JSON schema fragments across the README, website, and Action manifest.
• Site Catalog: MutineerSiteDocs in rake/site_docs.rb maintains the published URL catalog for sitemap.xml and llms.txt.
• YARD Stability: The build process normalizes YARD HTML footers (stripping timestamps and Ruby patch versions) so that regenerations only produce meaningful diffs.

Sources: rake/docs_contract.rb:10-50, rake/site_docs.rb:10-45, rake/yard_pages.rb:40-60