You can help by reporting compatibility differences, sharing real workloads,
improving documentation or contributing code. Look for
good first issue
for a starting point. Discuss substantial changes in an issue before implementing
them.
Report bugs and feature requests through the issue templates. Include the command, relevant input and observed output or errors. For a GNU compatibility difference, compare with GNU datamash 1.9 and check the documented differences. Report security problems privately through SECURITY.md.
Use Linux or WSL2, or macOS 15 or later, with the latest stable Rust. Website checks also need Python 3.10 or later. From a clone of the repository:
cargo build
./target/debug/fastmash --helpRead ARCHITECTURE.md for the code map and GLOSSARY.md for the vocabulary used in code, tests and issues. Design decisions explain the project's constraints.
Use focused local checks while developing. TESTING.md gives the commands and prerequisites for application, website, native macOS and tooling checks. It also explains how to prepare the test helpers before workspace tests. A complete local replay of CI is not required. Use CI for platform coverage unavailable locally. Applicable CI checks must pass before merging.
Add a regression test that fails without a bug fix, and matching expectations
for behavior changes. Update the user guide and --help when behavior changes.
Keep each pull request to one concern and separate refactoring from behavior
changes.
- Match GNU datamash 1.9 by default. An intentional compatibility difference needs a reason and an entry in the differences guide in the same change.
- Any change to printed numbers needs a new Numerical profile version and independent verification. Discuss it in an issue first and name the profile in the pull request.
- Performance-affecting runtime, dependency and build-recipe changes need before-and-after measurements against the previous accepted build on affected jobs and representative regression guards. A material regression needs a fix or an explicit disposition. Tie new speed claims to dated measurements. See the measurement method and PROFILING.md.
- First-party unsafe code is limited to the audited startup module and the two
existing GNU Linux allocator calls. Startup covers pre-runtime capture of
closed standard streams and the Linux process entry with its initial SIGPIPE
setup. The allocator exception covers only
mallopt(M_ARENA_MAX, arenas)andmalloc_trim(0)inmalloc_arenas.rs. Keep each operation minimal and explain its soundness with a// SAFETY:comment. Any extension needs a new maintainer decision. See ADR 0017 and ADR 0020. - Justify new dependencies and use licenses compatible with
MIT OR Apache-2.0. Use current stable dependencies with compatible ranges and commit lockfiles. Locale-reference updates have additional qualification requirements.
Create a branch in your fork and open a pull request against main once the
implementation and local checks are settled. All changes enter main through
a pull request. The maintainer reviews and merges after applicable CI passes.
Update your branch when intervening changes could affect it.
Use Problem, Solution and Validation in the pull request description. Explain the reason, behavior and compatibility effects, and meaningful checks. Put migration or upgrade instructions in Solution. Link the issue when there is one. Issue descriptions use Problem, Desired outcome and Evidence. Keep small changes brief.
Public descriptions and comments cover software behavior, technical rationale and evidence. Attribute checks accurately, keep private discussions out of public records and preserve reporters' observations. Before closing an implementation ticket, update its acceptance checklist and check whether its parent is complete.
Use a conventional title with a short imperative summary, such as
fix: Validate trimmean parameters or feat: Add a table operation.
Use perf: for measured performance changes, docs: for documentation and
fix(deps): for user-facing dependency updates. Internal work uses ci:,
build:, chore:, test: or refactor:.
The title becomes the short changelog entry. Use ! for a breaking change,
such as feat!: Rename an option, and explain compatibility consequences in
the description. Release notes are generated, so leave [Unreleased] empty
and do not add a release-note footer. Use public issue numbers in discussion
and full public issue links in source comments.
Contributions are dual licensed under MIT or Apache-2.0, at the user's option, without additional terms.