NethermindEth / NethermindEth/pluto

Fix `README`, `CONTRIBUTING`, and `AGENTS` drift

Open
#634 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
Rust
Stars
8
Forks
5
Avg merge
4d 16h
Merged PRs (30d)
37

Description

Summary

The top-level docs have drifted from the code in ways that actively mislead:

CONTRIBUTING.md

  • Claims nix develop provides the Rust toolchain — it doesn't (#598); also omits that quality gates need a nightly rustfmt, that smoke tests need Go, and that cargo test --all-features requires a running Docker daemon (eth2api's integration feature uses testcontainers) — a contributor without Docker gets opaque failures.
  • Doesn't mention that the pre-push hook runs deny + machete + fmt + clippy + the full test suite.
  • The profiling section fences TOML as ```rust and suggests dhat = "latest", which isn't a valid version requirement.

README.md

  • The "Version compatibility" section is copy-pasted from Charon ("two given versions of Charon are compatible if…") and never states Pluto's own promise or explains that the workspace version tracks the charon parity target.
  • No build/install/quickstart at all — nothing about the Dockerfile, the published image, or test-infra/; the examples list covers 6 of 11 examples.

AGENTS.md

  • The crate listing is 8 crates out of date: missing consensus, eth1wrap, featureset, frost, infosync, parsigex, priority, ssz; tree diagram omits third_party/ (load-bearing for charon interop in CI) and scripts/.

Cross-cutting: user-visible "Charon" branding in Pluto help text and crate docs — cli.rs long_about strings ("Verify that Charon can…", "Creates a local charon cluster configuration"), pluto-cluster/pluto-tracing module docs titled "# Charon …". Each needs a deliberate keep-or-rename decision (file/flag names like charon-enr-private-key are compatibility surface and should stay).

crates/cli/README.md's inverted parity table is already tracked by #584 — don't duplicate it here, but note cli.rs#L38 says "pluto-enr-private-key" while the actual default filename is charon-enr-private-key; the code comment is the wrong one.

Proposed change

One pass per file fixing the enumerated items; add a minimal Build/Run/Test quickstart to the README.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading README.md, CONTRIBUTING.md, and AGENTS.md alongside the workspace crate tree, Dockerfile, test-infra/, and the referenced cli.rs and module documentation. Check the listed toolchain, hooks, profiling, compatibility, quickstart, crate listing, and Charon-branding claims against the repository; avoid duplicating cli README parity work tracked by #584. Done means the enumerated documentation and comment drift is corrected and the keep-or-rename decisions are reflected consistently.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, rust
Domain
developer-experience, devops, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.