Contributing

How to contribute to Better PM development

Thank you for your interest in contributing to Better PM! This guide will help you get started with development, testing, and submitting changes.

Quick Start

Prerequisites

You’ll need:

Bun installed (v1.0 or later)
Git for version control
A GitHub account for pull requests

Development Setup

# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/better-pm.git
cd better-pm

bun install

# Run type checking
bun run check:tsc

# Test the CLI locally
bun entries/cli.ts i

Project Structure

Understanding the codebase structure will help you navigate and contribute effectively:

better-pm/
├── entries/
│   └── cli.ts              # Effect CLI bootstrap and entry point
├── src/
│   ├── commands/           # Command implementations
│   │   ├── install.ts      # pm i - monorepo-aware install
│   │   ├── add.ts          # pm add - add dependencies
│   │   ├── remove.ts       # pm remove - remove dependencies
│   │   ├── ls.ts           # pm ls - list workspace packages
│   │   ├── cd.ts           # pm cd - navigate to packages
│   │   └── activate.ts     # pm activate - shell integration
│   ├── pm/                 # Package manager abstraction
│   │   ├── pnpm.ts         # pnpm implementation
│   │   ├── bun.ts          # bun implementation
│   │   ├── npm.ts          # npm implementation
│   │   └── detect.ts       # Auto-detection logic
│   ├── project/
│   │   └── find-upward.ts  # Upward file traversal utility
│   └── lib/
│       └── errors.ts       # Tagged error definitions
├── scripts/
│   ├── build-npm.ts        # Build script for npm distribution
│   └── publish-npm.ts      # Publication script
└── bin.mjs                 # CLI entry point for npm distribution

Development Workflow

Making Changes

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
Edit the relevant files in src/ or add new commands in src/commands/

Test your changes

# Type check
bun run check:tsc

# Run tests
bun test

# Test CLI locally
bun entries/cli.ts <command> <args>

Format code
```
bun run format
```

Running Tests

Better PM uses Vitest for testing:

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run specific test file
bun test src/commands/install.test.ts

Code Style Guidelines

Better PM uses Biome for formatting and linting:

Formatting: Run bun run format before committing
Type safety: All code must pass TypeScript strict mode checks
Effect patterns: Follow Effect-TS best practices for error handling and composition
Naming: Use descriptive names for functions and variables

Testing Your Changes Locally

Before submitting a PR, test your changes in a real project:

# In the better-pm directory
bun link

# In your test project
bun link better-pm

# Now 'pm' will use your local development version
pm i
pm add lodash

Submitting Changes

Pull Request Process

Push your branch

git push origin feature/your-feature-name

Create a pull request
Go to github.com/fdarian/better-pm/pulls and create a new PR
Fill out the PR template
- Describe what your change does and why
- Link any related issues
- Include screenshots/examples if applicable
Wait for review
Maintainers will review your PR and may request changes

Commit Message Guidelines

Better PM uses Changesets for version management:

Write clear, descriptive commit messages
Use present tense (“Add feature” not “Added feature”)
Reference issues where applicable (Fixes #123)

Adding a Changeset

For changes that affect the public API or user-facing behavior:

bunx changeset

Follow the prompts to:

Select the type of change (major/minor/patch)
Write a summary of the change
Commit the generated changeset file

Contributing to Documentation

Documentation improvements are always welcome! You can:

Edit docs directly on GitHub by clicking “Edit this page” on any documentation page
Suggest improvements by opening an issue
Fix typos and improve clarity

Types of Contributions

We welcome various types of contributions:

Bug Fixes

Found a bug? Open an issue first to discuss it, then submit a PR with:

A test that reproduces the bug

The fix implementation

Updated documentation if needed

New Features

Want to add a new command or feature?

Open an issue to discuss the feature first

Ensure it aligns with Better PM’s goals

Include comprehensive tests

Update documentation and changelog

Performance Improvements

Optimizations are welcome! Include:

Benchmarks showing the improvement

Tests ensuring behavior hasn’t changed

Description of the optimization technique

Documentation

Help make Better PM easier to use:

Fix typos and unclear explanations

Add examples and use cases

Improve error messages

Expand getting started guides

Getting Help

Need help with your contribution?

GitHub Discussions: Ask questions and share ideas
Issues: Report bugs or request features
Discord: Join our community (link in README)

Code of Conduct

Be respectful and constructive in all interactions. We’re building Better PM together, and everyone’s contributions are valued.