MerceMay

CONTRIBUTING.md

3.2 KB · 98 lines · · 2ed4c1f
# Contributing to ripgrab

Thanks for your interest. ripgrab is a small tool and I try to keep the
process light. The project lives at `mercemay.top/src/ripgrab/` and this
document describes how to propose changes.

## Before you start

For anything beyond a small bug fix or typo, please open an issue first
with a short description of what you want to change and why. Most
patches that get rejected are rejected for scope reasons, not quality
reasons, so that conversation saves you time.

If you are unsure whether an idea fits, open the issue anyway. I would
rather say "not now" than have you write code that I cannot merge.

## Development setup

Rust 1.76 or newer is required (`rust-version` in `Cargo.toml` is the
source of truth). Clone and build:

```sh
git clone https://mercemay.top/src/ripgrab/
cd ripgrab
cargo build
cargo test

The benchmark suite uses criterion and is gated behind the default dev-dependencies:

cargo bench --bench filter_bench

Code style

  • Run cargo fmt --all before committing. CI will fail the formatting check otherwise. The style is configured in .rustfmt.toml.
  • Run cargo clippy --all-targets -- -D warnings. Clippy runs on CI with warnings promoted to errors.
  • Prefer named structs over tuples when you have more than two fields.
  • Public items must be documented. #![warn(missing_docs)] is enabled on the library crate.

Testing

  • Unit tests go next to the code in #[cfg(test)] modules.
  • Integration tests go under tests/. We use assert_cmd + predicates and write output fixtures into tempfile::TempDir.
  • When you add a new filter rule or extractor, add at least one positive and one negative test case.

Commits

Commit messages follow the form:

<module>: <short lowercase summary>

<optional longer body wrapped at 72 columns>

Examples:

  • filter: compile regex set once per session
  • tail: handle truncation / rotation on inode change
  • render: honor NO_COLOR env var

<module> is usually the top-level module the change affects (filter, tail, render, cli, ci, deps, docs). Breaking changes get a trailing ! after the module and a BREAKING CHANGE: line in the body.

Pull requests

  • Keep them small. One logical change per PR.
  • Rebase on top of main before asking for review; I do not squash-merge so the commit history is what lands.
  • If the change affects the CLI surface or the library API, update CHANGELOG.md under the [Unreleased] section.
  • CI must be green. There is no “fix CI in a follow-up” policy here.

Releasing

Only maintainers release. The steps are recorded in docs/architecture.md; in short:

  1. Bump version in Cargo.toml.
  2. Move [Unreleased] entries to a new dated section in CHANGELOG.md.
  3. Tag vX.Y.Z; the release workflow in .github/workflows/release.yml picks it up from there.

Reporting bugs

Please include the output of ripgrab --version, a short reproducer (ideally a small log file and the exact arguments), and your operating system. A core dump is not required.