Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
201 lines (135 loc) · 6.95 KB

CONTRIBUTING.md

File metadata and controls

201 lines (135 loc) · 6.95 KB

Contributing to rtk-plus

Welcome! We appreciate your interest in contributing to rtk-plus.

rtk-plus is an extended fork of rtk-ai/rtk. For contributions to the core project, please submit PRs upstream.

Quick Links

What is rtk-plus?

rtk-plus is an extended fork of rtk (Rust Token Killer), a coding agent proxy that cuts noise from command outputs. It filters and compresses CLI output before it reaches your LLM context, saving 60-90% of tokens on common operations. This fork adds additional command patterns, broader regex coverage, and quality-of-life fixes.

Ways to Contribute

Type Examples
Report File a clear issue with steps to reproduce, expected vs actual behavior
Fix Bug fixes, broken filter repairs
Build New filters, new command support, performance improvements
Review Review open PRs, test changes locally, leave constructive feedback
Document Improve docs, add usage examples, clarify existing docs

Branch Naming Convention

Every branch must follow one of these prefixes to identify the level of change:

Prefix Semver Impact When to Use
fix(scope): ... Patch Bug fixes, corrections, minor adjustments
feat(scope): ... Minor New features, new filters, new command support
chore(scope): ... Major Breaking changes, API changes, removed functionality

The scope in parentheses indicates which part of the project is concerned (e.g. git, kubectl, filter, tracking, config).

Branch title must clearly describe what is affected and the goal.

Examples:

fix(git): log-filter-drops-merge-commits
feat(kubectl): add-pod-list-filter
chore(proxy): remove-deprecated-flags

Pull Request Process

1. Create Your Branch

git checkout develop
git pull origin develop
git checkout -b "feat(scope): your-clear-description"

2. Make Your Changes

Respect the existing folder structure. Place new files where similar files already live. Do not reorganize without prior discussion.

Keep functions short and focused. Each function should do one thing. If it needs a comment to explain what it does, it's probably too long -- split it.

No obvious comments. Don't comment what the code already says. Comments should explain why, never what to avoid noise.

Large command files are expected. Command modules (*_cmd.rs) contain the implementation, tests, and fixture in the same file. A big file is fine when it's self-contained for one command.

3. Add Tests

Every change must include tests. See Testing below.

4. Add Documentation

Every change must include documentation updates. See Documentation below.

Developer Certificate of Origin (DCO)

All contributions must be signed off (git commit -s) to certify you have the right to submit the code under the project's license.

Expected format: Signed-off-by: Your Name your@email.com https://developercertificate.org/

By signing off, you agree to the DCO.

5. Merge into develop

Once your work is ready, open a Pull Request targeting the develop branch.

6. Review Process

  1. Maintainer review -- A maintainer reviews your code for quality and alignment with the project
  2. CI/CD checks -- Automated tests and linting must pass
  3. Resolution -- Address any feedback from review or CI failures

7. Integration & Release

Once merged, your changes are tested on the develop branch alongside other features. When the maintainer is satisfied with the state of develop, they release to master under a specific version.

your branch --> develop (review + CI + integration testing) --> version branch --> master (versioned release)

Testing

Every change must include tests. We follow TDD (Red-Green-Refactor): write a failing test first, implement the minimum to pass, then refactor.

Test Types

Type Where Run With
Unit tests #[cfg(test)] mod tests in each module cargo test
Snapshot tests assert_snapshot!() via insta crate cargo test + cargo insta review
Smoke tests scripts/test-all.sh (69 assertions) bash scripts/test-all.sh
Integration tests #[ignore] tests requiring installed binary cargo test --ignored

How to Write Tests

Tests for new commands live in the module file itself inside a #[cfg(test)] mod tests block (e.g. tests for src/kubectl_cmd.rs go at the bottom of that same file).

1. Create a fixture from real command output (not synthetic data):

kubectl get pods > tests/fixtures/kubectl_pods_raw.txt

2. Write your test in the same module file (#[cfg(test)] mod tests):

#[test]
fn test_my_filter() {
    let input = include_str!("../tests/fixtures/my_cmd_raw.txt");
    let output = filter_my_cmd(input);
    assert_snapshot!(output);
}

3. Verify token savings:

#[test]
fn test_my_filter_savings() {
    let input = include_str!("../tests/fixtures/my_cmd_raw.txt");
    let output = filter_my_cmd(input);
    let savings = 100.0 - (count_tokens(&output) as f64 / count_tokens(input) as f64 * 100.0);
    assert!(savings >= 60.0, "Expected >=60% savings, got {:.1}%", savings);
}

Pre-Commit Gate (mandatory)

All three must pass before any PR:

cargo fmt --all --check && cargo clippy --all-targets && cargo test

PR Testing Checklist

  • Unit tests added/updated for changed code
  • Snapshot tests reviewed (cargo insta review)
  • Token savings >=60% verified
  • Edge cases covered
  • cargo fmt --all --check && cargo clippy --all-targets && cargo test passes
  • Manual test: run rtk <cmd> and inspect output

Documentation

Every change must include documentation updates. Update the relevant file(s) depending on what you changed:

What you changed Update
New command or filter README.md (command list + examples) and CHANGELOG.md
Architecture or internal design ARCHITECTURE.md
Installation or setup INSTALL.md
Bug fix or breaking change CHANGELOG.md
Tracking / analytics docs/tracking.md

Keep documentation concise and practical -- examples over explanations.

Questions?

For external contributors: Your PR will undergo automated security review (see SECURITY.md). This protects RTK's shell execution capabilities against injection attacks and supply chain vulnerabilities.

Thank you for contributing to rtk-plus!