Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
165 lines (118 loc) · 5.76 KB

CONTRIBUTING.md

File metadata and controls

165 lines (118 loc) · 5.76 KB
Raw

Contributing to dev-prune

Thank you for your interest in contributing to dev-prune (devp)! We welcome contributions from engineers of all experience levels.

dev-prune is written in modern Rust (Edition 2024) and designed to be highly modular, testable, and contribution-friendly.

🛠️ Prerequisites & Local Development Setup

1. Requirements

  • Rust Toolchain: 1.88 or newer (rustup update stable)
  • Components: rustfmt, clippy (rustup component add rustfmt clippy)
  • Node.js (optional, for web landing page under site/): 20+

2. Clone & Build

git clone https://github.com/Life-Experimentalist/dev-prune.git
cd dev-prune

# Build debug binary
cargo build

Before opening a pull request, run the same four commands CI runs, on the same flags. The flags matter: --all-targets is what puts test code under clippy, and without --all-features a feature-gated path goes unchecked locally and fails in CI instead.

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all --all-features
npm --prefix site run build

3. Windows: set the execution policy before running any .ps1

scripts/install.ps1 and the other PowerShell scripts in this repository are files, and PowerShell's execution policy governs files. The default for a user account is RemoteSigned, so running one from your checkout stops with:

File install.ps1 cannot be loaded because running scripts is disabled on this system.

Scope the relaxation to the one process that needs it, rather than changing the machine:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1 -NoAutoSetup

The setting dies with that process. Prefer it to Set-ExecutionPolicy, which changes the policy for every script you run from then on — a permanent change to your machine bought to run one script once. If you would rather set it for your own session only, that is Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass, which lasts until you close the window.

None of this applies to the published one-liner. iwr … | iex evaluates a string and never creates a file, so there is nothing for the policy to govern — which is also why the -ExecutionPolicy Bypass in the documented cmd.exe command is belt-and-braces rather than load-bearing.

📦 How to Add a New Package Manager Adapter

dev-prune uses a simple, extensible PackageManager trait defined in src/adapters/mod.rs.

To add support for a new ecosystem (e.g. maven, gradle, composer, mix, swift):

  1. Create module file: Create src/adapters/my_adapter.rs.
  2. Implement trait: Implement PackageManager trait (name, detect, bloat_dirs, enforce_lockfile, restore).
  3. Register adapter: Add pub mod my_adapter; and register Box::new(my_adapter::MyAdapter) in get_all_adapters() inside src/adapters/mod.rs.
  4. Add unit tests: Use tempfile::TempDir to test detect, bloat_dirs, name uniqueness, and lockfile safety.

See the detailed step-by-step tutorial: How to Add a New Package Manager Adapter (docs/ADDING_ADAPTERS.md).

🌐 How to Add or Fix a Translation

dev-prune prints its own headings and summary lines in twelve languages. Adding a thirteenth is one JSON file in src/i18n/locales/ and one include_str! line in src/i18n/mod.rs; fixing a wrong sentence in an existing one touches no Rust at all.

Translations are deliberately bounded: --json, exit codes, flag names, config keys, adapter names and lockfile refusals are English in every catalogue, because they are a contract or a diagnosis rather than chrome. Read the boundary before you translate anything.

Every catalogue but English currently carries "reviewed": false, and the tool says so when somebody picks it. If you are a native speaker and you have read a file through, flipping that flag is a welcome pull request on its own.

See: Translating dev-prune (docs/TRANSLATIONS.md).

🧪 Local Testing Workflow

Safe Local Installation

Install dev-prune locally to test subcommands without affecting global binaries:

cargo install --path .

Run CLI commands:

# Scan current directory
dev-prune init .

# Check status dashboard
dev-prune status

# Simulate prune pass safely
dev-prune run --dry-run

🎨 Local Site / Landing Page Development

If you'd like to test the React site landing page locally:

cd site
npm install
npm run dev

To test the pre-compiled production build:

npm run build

📜 Pull Request Checklist

Before submitting a pull request, verify:

  • Code is formatted with cargo fmt
  • Lints pass clean with cargo clippy -- -D warnings
  • All unit and integration tests pass with cargo test --all
  • New adapters or features include unit tests using tempfile::TempDir
  • Documentation and comments are updated to reflect code changes
  • Every new source file starts with the two-line licence header (see below)

⚖️ Licensing

dev-prune is Apache-2.0. Contributing means agreeing that your contribution is licensed the same way — the terms are in section 5 of LICENSE.md, and there is no separate CLA to sign.

Every source file starts with these two lines, using whatever comment syntax the language wants (//, #, /* */), directly below the shebang if there is one:

// Copyright 2026 VKrishna04
// SPDX-License-Identifier: Apache-2.0

That is the short form of the boilerplate in the appendix of LICENSE.md. It says the same thing in one line that automated licence scanners can read, which the thirteen-line prose version does not.