A compact summary of how to work on Fastmash, for contributors and the coding tools they use. CONTRIBUTING.md is the full guide.
- Fastmash is a Rust command-line program for Linux x86-64 that implements the GNU datamash command language with faster, portable results.
- Read GLOSSARY.md before naming anything. Use its terms in code, tests, comments and issues, and avoid the synonyms it lists under Avoid.
- Read ARCHITECTURE.md for the crates, the request pipeline
and the design principles. Decisions are recorded in
docs/src/adr/. If a proposal conflicts with a decision, name the decision and explain the conflict. - The user guide in
docs/src/describes promised behavior. Treat a mismatch between the guide and the code as a bug in one of them, and say which.
For performance diagnosis or profiling setup, read PROFILING.md before building or capturing a report. It defines the shared profiling workflow and keeps diagnostic captures separate from acceptance measurements.
For documentation-only changes (docs/** and Markdown files), run the
website checks. Application changes run the
application checks. Changes to build or CI tooling
need checks of the affected tooling and workflow filters. Report any check
you could not run. On Windows, use WSL2 with the checkout on the Linux filesystem.
- Do not change numerical output silently. A change that can alter any printed number requires a new numerical profile version, independent verification and a changelog entry. If you are unsure whether a change affects numbers, assume it does and say so.
- Match GNU datamash by default. For a compatibility question, check what
GNU datamash 1.9 actually does. Intentional differences go in
docs/src/guide/differences.mdin the same change. - Refuse rather than guess. Unsupported conditions exit with status 77 and a clear diagnostic. Errors in the command or input exit with status 1. Never replace a refusal with a best-effort result.
- Keep storage growable and checked. Do not add new fixed caps on records, fields, groups or samples. Handle allocation failure as a refusal.
- Measure performance claims. Do not claim a speedup without before-and-after measurements on the same host and build settings.
- No
unsafewithout need. Newunsafecode requires a// SAFETY:comment and a reason in the pull request. - No new dependencies without justification, and only with licenses
compatible with
MIT OR Apache-2.0. - No GNU code. Fastmash reimplements behavior. Do not copy, translate or paraphrase code from GNU datamash or other GPL sources. Describing observable behavior is fine.
- Never write "datamash" in identifiers, crate names or program messages. Documentation may compare the two programs.
- Tests accompany changes. A bug fix adds a test that fails without it.
All changes enter main through a pull request. The maintainer uses a
contrib/ branch in this repository; contributors use a branch in their fork.
Follow the development workflow in CONTRIBUTING.md.
Follow Testing for focused local checks and final CI validation. Leave review and merging to the maintainer once CI passes. Before closing a ticket, update its acceptance checklist and check whether its parent can close.
Describe what changed, why, how it was tested, and any effect on output, exit statuses, performance or documentation. Keep each pull request to one concern.