Your First Contribution: Documentation & Tests

Learning Objectives

• Improve documentation (doc comments, README, or guides)
• Add or improve unit tests
• Fix a small bug or clarify code
• Submit a PR and respond to review

1. Why Start with Docs and Tests?

Documentation and tests are the safest way to get familiar with the codebase and the project’s workflow:

• Low risk – You don’t change core behavior; you make the code easier to understand and more reliable.
• High value – Good docs and tests help everyone, including future you.
• Reviewable – Maintainers can focus on clarity and correctness without needing deep protocol knowledge; that makes review smoother and helps you learn the codebase by explaining or testing it.

2. Finding Good First Issues

Look for:

• Issues labeled good first issue, documentation, or testing
• Functions or modules with missing or unclear doc comments (run cargo doc and browse)
• Code paths with no or few tests (check #[cfg(test)] modules and coverage if available)

Guideline: claim the issue first. Before coding, comment on the issue to say you're working on it (e.g. "I'll take this") and give a one-line plan. That avoids duplicate work, lets maintainers steer you if your approach is off, and sets expectations so your PR has a better chance of a smooth review.

3. Documentation Guidelines

• Rust doc comments – Use /// on public items. Describe what the type or function is for, any invariants, and panics/errors if relevant.
• Guides – The guides/ directory in the repo holds longer explanations (overview, architecture, codebase structure, consensus protocol). Follow the existing style and structure.
• README / CONTRIBUTING – Small clarifications (e.g. setup steps, prerequisites) are often welcome.

4. Testing Guidelines

• Use the existing test patterns: unit tests next to the code, integration tests in tests/ or under crates/*/tests.
• Determinism makes tests easier: State machines in hyperscale-rs are deterministic — same initial state + same sequence of events ⇒ same actions every time. Use that to write deterministic tests: no flaky timing, no need to mock the network or sleep for timeouts. Build the state machine, feed events in order, assert on actions; tests are repeatable and fast, and a failure points to a real logic bug.
• If you add a test for a bug fix, make sure the test fails before the fix and passes after.

5. Submitting Your PR

1. Fork the repo (if that’s the project’s workflow) and create a branch, e.g. docs/improve-core-traits or tests/add-event-coverage.
2. Keep the PR small: one logical change (one doc improvement, one test file, or one small bug fix).
3. PR description format: Reference the issue (e.g. Fixes #42 or Closes #42) so reviewers see what you're addressing. Explain what you did and why, and how you verified it (e.g. "Added unit tests for handle(ProposalTimer) when node is proposer; ran cargo test, all tests pass"). That context makes review faster and shows you're thinking about verification, not just pushing code.
4. Commit message format: Follow the project's convention if documented (e.g. in CONTRIBUTING.md). A common pattern is a short subject line (imperative, <72 chars) and optional body: e.g. docs(core): clarify StateMachine trait contract or test(bft): add ProposalTimer proposer path. If the project uses conventional commits or "type(scope): message", match that style.
5. Run cargo test and cargo doc (and any other checks the repo uses) and fix any failures.
6. Respond to review feedback promptly and update the PR accordingly.

6. Practical Assignment