Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
393 lines (310 loc) · 12.6 KB

CONTRIBUTING.md

File metadata and controls

393 lines (310 loc) · 12.6 KB

Contributing to Pacsea

Thanks for your interest in contributing! Pacsea is a fast, keyboard-first TUI for discovering and installing Arch and AUR packages.

By participating, you agree to follow our Code of Conduct.

For newcomers looking to contribute, we recommend starting with issues labeled "Good First Issue" in our issue tracker.

Ways to contribute

  • Bug reports and fixes
  • Feature requests and implementations
  • Documentation and examples
  • UI/UX polish and accessibility improvements
  • Translations and localization

Before you start

  • Target platform: Pacsea focuses on Arch Linux and Arch-based distributions (e.g., EndeavourOS, Manjaro, CachyOS, Artix). End-to-end install/update features rely on Arch tools like pacman and an AUR helper (paru or yay).
  • Safety: During development, prefer --dry-run and/or a disposable VM/container to avoid unintended changes.
  • Security: If your report involves a security issue, use our Security Policy.

Development setup

Prerequisites

  1. Install Rust (stable): 
    sudo pacman -S rustup && rustup default stable
  2. Clone the repository: 
    git clone https://github.com/Firstp1ck/Pacsea
cd Pacsea

Running the application

# Basic run (dry-run mode recommended for development)
cargo run -- --dry-run

# With debug logging
RUST_LOG=pacsea=debug cargo run -- --dry-run

# Or use verbose flag
cargo run -- --dry-run --verbose

Running tests

Tests must be run single-threaded to avoid race conditions:

cargo test -- --test-threads=1
# or
RUST_TEST_THREADS=1 cargo test

Code quality requirements

Pre-commit checklist

Before committing, ensure all of the following pass:

  1. Format code:

    cargo fmt --all

  2. Lint with Clippy:

    cargo clippy --all-targets --all-features -- -D warnings

    The project uses strict Clippy settings configured in Cargo.toml:

    [lints.clippy]
cognitive_complexity = "warn"
pedantic = { level = "deny", priority = -1 }
nursery = { level = "deny", priority = -1 }
unwrap_used = "deny"

    Additional settings in clippy.toml:

    • cognitive-complexity-threshold = 25
    • too-many-lines-threshold = 150

  3. Check compilation:

    cargo check

  4. Run tests:

    cargo test -- --test-threads=1

  5. Check complexity (for new code):

    # Run complexity tests to ensure new functions meet thresholds
cargo test complexity -- --nocapture

    Complexity thresholds:

    • Cyclomatic complexity: Should be < 25 for new functions
    • Data flow complexity: Should be < 25 for new functions

    See Development wiki for detailed complexity analysis.

Code documentation requirements

For all new code (functions, methods, structs, enums):

  1. Rust documentation comments are required:

    /// What: Brief description of what the function does.
///
/// Inputs:
/// - `param1`: Description of parameter 1
/// - `param2`: Description of parameter 2
///
/// Output:
/// - Description of return value or side effects
///
/// Details:
/// - Additional context, edge cases, or important notes
pub fn example_function(param1: Type1, param2: Type2) -> Result<Type3> {
    // implementation
}

  2. Documentation should include:

    • What: What the function/method does
    • Inputs: All parameters with descriptions
    • Output: Return value, side effects, or state changes
    • Details: Important implementation details, edge cases, or usage notes

Testing requirements

For bug fixes:

  1. Create failing tests first that reproduce the issue
  2. Fix the bug
  3. Verify tests pass
  4. Add additional tests for edge cases if applicable

For new features:

  1. Add unit tests for new functions/methods
  2. Add integration tests for new workflows
  3. Test error cases and edge conditions
  4. Ensure tests are meaningful and cover the functionality

Test guidelines:

  • Tests should be deterministic and not rely on external state
  • Use --dry-run in tests that would modify the system

Commit and branch guidelines

Branch naming

  • feat/<short-description> — New features
  • fix/<short-description> — Bug fixes
  • docs/<short-description> — Documentation only
  • refactor/<short-description> — Code refactoring
  • test/<short-description> — Test additions/updates
  • chore/<short-description> — Build/infrastructure changes

Commit messages

Prefer Conventional Commits format:

<type>: <short summary>

<optional longer description>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • refactor: Code refactoring (no functional change)
  • perf: Performance improvements
  • test: Test additions or updates
  • chore: Build/infrastructure changes
  • ui: Visual/interaction changes
  • breaking change: Incompatible behavior changes

Examples:

feat: add fuzzy search functionality

- Implemented fzf-style matching for package searches
- Added CTRL+F toggle for fuzzy search mode
- Updated localization files for new feature

fix: resolve reverse dependencies in preflight modal

Fixes issue where reverse dependencies were not shown when
removing packages. Now correctly displays packages that depend
on the package being removed.

Guidelines:

  • Keep commits focused and reasonably small
  • Add rationale in the body if the change is non-obvious
  • Reference issue numbers if applicable: Closes #123 or Fixes #456

Pull Request process

Before opening a PR

  1. Ensure all quality checks pass:

    • cargo fmt --all (no changes needed)
    • cargo clippy --all-targets --all-features -- -D warnings (clean)
    • cargo check (compiles successfully)
    • cargo test -- --test-threads=1 (all tests pass)
    • Complexity checks pass for new code

  2. Code requirements:

    • All new functions/methods have rustdoc comments (What, Inputs, Output, Details)
    • Code follows project conventions (see below)
    • No unwrap() or expect() in non-test code (use proper error handling)
    • Complexity thresholds met (cyclomatic < 25, data flow < 25)

  3. Testing:

    • Added/updated tests where it makes sense
    • For bug fixes: created failing tests first, then fixed the issue
    • Tests are meaningful and cover the functionality

  4. Documentation:

    • Updated README if behavior, options, or keybinds changed
    • Updated wiki pages if needed (see Wiki)
    • Updated config examples if config keys changed
    • For UI changes: included screenshots and updated Images/ if applicable

  5. Compatibility:

    • Changes respect --dry-run flag
    • Code degrades gracefully if pacman/paru/yay are unavailable
    • No breaking changes (or clearly documented if intentional)

PR description template

Use the following structure for your PR description (see Documents/PR_DESCRIPTION.md for a template):

## Summary
Brief description of what this PR does.

**Bug Fixes:**
1. Description of bug fix 1
2. Description of bug fix 2

**New Features:**
1. Description of new feature 1
2. Description of new feature 2

## Type of change
- [ ] feat (new feature)
- [ ] fix (bug fix)
- [ ] docs (documentation only)
- [ ] refactor (no functional change)
- [ ] perf (performance)
- [ ] test (add/update tests)
- [ ] chore (build/infra/CI)
- [ ] ui (visual/interaction changes)
- [ ] breaking change (incompatible behavior)

## Related issues
Closes #123

## How to test
Step-by-step testing instructions.

## Checklist
- [ ] Code compiles locally
- [ ] `cargo fmt --all` ran without changes
- [ ] `cargo clippy --all-targets --all-features -- -D warnings` is clean
- [ ] `cargo test -- --test-threads=1` passes
- [ ] Added or updated tests where it makes sense
- [ ] Updated docs if behavior, options, or keybinds changed
- [ ] For UI changes: included screenshots and updated `Images/` if applicable
- [ ] Changes respect `--dry-run` and degrade gracefully if `pacman`/`paru`/`yay` are unavailable
- [ ] If config keys changed: updated README/wiki sections for `settings.conf`, `theme.conf`, and `keybinds.conf`
- [ ] Not a packaging change for AUR (otherwise propose in `pacsea-bin` or `pacsea-git` repos)

## Notes for reviewers
Any additional context, implementation details, or decisions that reviewers should know.

## Breaking changes
None (or description of breaking changes if applicable)

## Configuration
If new config keys were added, document them here.

Project conventions

Code style

  • Language: Rust (edition 2024)
  • Naming: Clear, descriptive names. Favor clarity over brevity.
  • Error handling: Use Result types. Avoid unwrap()/expect() in non-test code.
  • Early returns: Prefer early returns over deep nesting.
  • Logging: Use tracing for diagnostics. Avoid noisy logs at info level.

UX guidelines

  • Keyboard-first: Minimal keystrokes, Vim-friendly navigation
  • Help overlay: Update help overlay if shortcuts change
  • Keybind docs: Update Keyboard Shortcuts wiki if keybinds change

Configuration

  • Config keys: If you add/change config keys:
    • Update config/settings.conf, config/theme.conf, or config/keybinds.conf examples
    • Update Configuration wiki
    • Update README if it's a major feature
    • Ensure backward compatibility when possible

Platform behavior

  • Dry-run: All commands must respect --dry-run flag
  • Graceful degradation: Commands must degrade gracefully if pacman/paru/yay are unavailable
  • Error messages: Provide clear, actionable error messages

Documentation updates

When updating documentation:

  1. README.md: Keep high-level, reference wiki for details

  2. Wiki pages: Update relevant wiki pages with detailed information:

  3. Config examples: Update example config files in config/ directory

Filing issues

Bug reports

Include the following information:

  • Pacsea version (e.g., 0.5.2 or commit hash)
  • Arch Linux version or distribution
  • Terminal emulator and version
  • Display server (Wayland/X11)
  • AUR helper (paru/yay) and version
  • Steps to reproduce
  • Expected vs. actual behavior
  • Logs (run with RUST_LOG=pacsea=debug or --verbose)

Example:

**Version**: 0.5.2
**Distribution**: Arch Linux (kernel 6.x)
**Terminal**: alacritty 0.13.x
**Display**: Wayland
**AUR Helper**: paru 1.11.x

**Steps to reproduce:**
1. Launch pacsea
2. Search for "firefox"
3. Press Space to add to install list
4. Press Enter

**Expected**: Preflight modal opens
**Actual**: Application crashes

**Logs:**
[Include relevant log output]

Feature requests

  • Describe the problem being solved
  • Describe the desired UX/behavior
  • Include mockups or keybind suggestions if applicable
  • Consider edge cases and compatibility

Open issues in the issue tracker.

Packaging notes

  • AUR packages live in separate repos: pacsea-bin and pacsea-git
  • Propose packaging changes in those repos rather than here
  • Version bumps should be coordinated with AUR package maintainers

Code of Conduct and Security

Getting help

  • Check the Wiki for documentation
  • Review existing issues and PRs
  • Ask questions in Discussions

Thank you for helping improve Pacsea!

Support indirectly

If you want to support the project, please vote on the AUR: Pacsea

If Pacsea has been helpful, you can support ongoing development here ❤️ Patreon