Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
119 lines (79 loc) · 4.51 KB

CONTRIBUTING.md

File metadata and controls

119 lines (79 loc) · 4.51 KB
Raw

Contributing to ReductStore CLI

Thanks for contributing.

We want ReductStore CLI to be easy to contribute to, especially for people joining the project for the first time. This guide keeps the workflow clear so you can spend more time building and less time guessing what reviewers expect.

Start with an Issue

Open a pull request only for an existing issue.

  • If you want to work on an issue, say so in the comments first and wait to be assigned before you start coding.
  • If you want to fix a reported bug, comment on the issue first so maintainers know you are working on it.
  • If you have a new idea, do not open a surprise PR. Start with a GitHub issue or a thread on the ReductStore community forum to discuss scope first.
  • If you want a small first task, start with good first issue.

Prepare Your Branch

Before you start coding:

  1. Sync your fork with the latest upstream/main (or update your local main from origin/main if you work directly in the repository).
  2. Create a fresh branch from the latest main.
  3. Keep the branch focused on one issue.

This repository expects every PR to be based on the newest default branch commit. If possible, start the branch name with the issue ID, for example 246-replication-prefix. It helps keep PRs easier to organize and review.

Run ReductStore Locally

If your change affects runtime behavior, start a real ReductStore instance and test it yourself when possible.

Please validate the changed path against a live server, not only with unit tests. Contributors should run the CLI from their branch, not only the published binary, so the command actually includes their changes.

For most changes, start ReductStore locally:

docker run --network=host --env RS_API_TOKEN=TOKEN -d reduct/store:main

Then run the CLI from your branch:

cargo run -- alias add local -L http://127.0.0.1:8383 -t TOKEN
cargo run -- server status local

Exercise the bucket, token, replication, lifecycle, attachment, cp, or rm path that your change touches.

Build and Test

Run the smallest relevant set locally before opening a PR:

cargo fmt --all
cargo check --locked
cargo test --locked

Useful follow-ups when they apply:

  • cargo clippy --locked
  • RS_API_TOKEN=TOKEN cargo test --locked -- --test-threads=1
  • cargo run -- <args>

If you skip a test, explain why in the PR.

AI-Assisted Changes

Generated code is allowed.

But the contributor submitting the PR is responsible for it:

  • Read and understand every generated change before you submit it.
  • Remove dead code, vague comments, and accidental scope creep.
  • Re-run tests and manual checks yourself.
  • Be ready to explain the design and tradeoffs in review.

Human judgment is required. "The AI wrote it" is not enough.

Open the Pull Request

When you open the PR:

  • Link the issue it resolves.
  • Use the repository pull request template.
  • Explain the user or maintainer problem you fixed.
  • List the validation you ran, including manual runtime checks when applicable.
  • Mention command, output, config, or environment changes that help reviewers verify behavior quickly.
  • Update CHANGELOG.md when the change affects users, operators, or client-visible behavior.
  • Keep screenshots, logs, or request examples when they help reviewers verify behavior quickly.

Update the Changelog

If your PR changes behavior that users may notice, add an entry to CHANGELOG.md.

  • Add the entry in the relevant unreleased section.
  • Keep it short and factual.
  • Focus on what changed for users or operators, not on internal refactoring details.
  • Include the pull request number if the surrounding entries already follow that style.
  • Skip changelog noise for purely internal changes with no user-facing effect.

Review Expectations

Recent contributor PRs in this repository show a consistent pattern:

  • Well-scoped PRs tied to an issue move faster.
  • Changes that come with local validation are easier to review.
  • Ambiguous feature additions usually need issue discussion before code review starts.
  • Maintainers may ask for behavior changes, test updates, or smaller scope before merge.

Treat review as collaboration. The goal is to help each other land solid changes with as little friction as possible.

Need Help?

  • Ask on the community forum
  • Comment on the issue you want to work on
  • Open a draft PR early if you want feedback on direction