Skip to content

Latest commit

 

History

History
373 lines (276 loc) · 11.1 KB

CONTRIBUTING.md

File metadata and controls

373 lines (276 loc) · 11.1 KB

Contributing to Clack

Thank you for your interest in contributing to Clack! This document provides detailed instructions for setting up your development environment, navigating the codebase, making changes, and submitting contributions.

Tip

For new contributors: Take a look at https://github.com/firstcontributions/first-contributions for helpful information on contributing to open source projects.

Getting Started

Prerequisites

  • Node.js (version specified in .nvmrc, currently v20.18.1)
  • pnpm (version 9.14.2 or higher)

If you use volta or nvm, the correct Node.js version will be automatically selected based on the project's .nvmrc file.

Local Development Setup

  1. Fork the repository:

    git clone https://github.com/YOUR_USERNAME/clack.git
cd clack

  2. Set up the upstream remote:

    git remote add upstream https://github.com/bombshell-dev/clack.git

  3. Install dependencies:

    pnpm install

  4. Build the packages:

    pnpm build

  5. Run the development server:

    pnpm dev

Using Clack Packages in Your Own Projects During Development

If you want to test changes to Clack packages in your own project, you can use pnpm's linking capabilities:

  1. Build the Clack packages locally first:

    # In the clack repository
cd /path/to/clack
pnpm build

  2. Link the packages to your project using one of these methods:

    Method 1: Using pnpm link

    # In your project
cd /path/to/your-project

# Link @clack/core
pnpm link --global /path/to/clack/packages/core

# Link @clack/prompts
pnpm link --global /path/to/clack/packages/prompts

    Method 2: Using local path in package.json

    In your project's package.json, reference the local paths:

    {
  "dependencies": {
    "@clack/core": "file:/path/to/clack/packages/core",
    "@clack/prompts": "file:/path/to/clack/packages/prompts"
  }
}

    Then run pnpm install in your project.

  3. Watch for changes (optional):

    # In the clack repository
cd /path/to/clack
pnpm build --watch

  4. Refresh after changes: If you're making changes to Clack while testing in your project, you'll need to rebuild Clack and potentially reinstall in your project:

    # In the clack repository
cd /path/to/clack
pnpm build

# In your project (if using Method 2)
cd /path/to/your-project
pnpm install

With this setup, you can develop and test your changes to Clack within the context of your own project. This is especially useful for implementing new features like filtering.

Repository Structure

Clack is organized as a monorepo using pnpm workspaces. Understanding the structure will help you navigate and contribute effectively:

clack/
├── .changeset/         # Changeset files for versioning
├── .github/            # GitHub workflows and templates
├── examples/           # Example implementations of Clack
├── packages/           # Core packages
│   ├── core/           # Unstyled primitives (@clack/core)
│   └── prompts/        # Ready-to-use components (@clack/prompts)
├── biome.json          # Biome configuration
├── package.json        # Root package.json
├── pnpm-workspace.yaml # Workspace configuration
└── tsconfig.json       # TypeScript configuration

Key Packages

  1. @clack/core (packages/core/):

    • Contains the unstyled, extensible primitives for building CLI applications
    • The foundation layer that provides the core functionality

  2. @clack/prompts (packages/prompts/):

    • Built on top of @clack/core
    • Provides beautiful, ready-to-use CLI prompt components
    • What most users will interact with directly

Examples

The examples/ directory contains sample projects that demonstrate how to use Clack. Examining these examples is a great way to understand how the library works in practice.

Development Workflow

Common Commands

  • Build all packages:

    pnpm build

  • Start development environment:

    pnpm dev

  • Run tests:

    pnpm test

  • Lint code:

    pnpm lint

  • Format code:

    pnpm format

  • Type check:

    pnpm type-check

  • Build stubbed packages (for faster development):

    pnpm stub

Making Changes

  1. Create a new branch:

    git checkout -b my-feature-branch

  2. Implement your changes:

    • For bug fixes, start by reproducing the issue
    • For new features, consider how it fits into the existing architecture
    • Maintain type safety with TypeScript
    • Add or update tests as necessary

  3. Run local verification:

    # Ensure everything builds
pnpm build

# Check formatting and lint issues
pnpm format
pnpm lint

# Verify type correctness
pnpm type-check

# Run tests
pnpm test

  4. Create a changeset (for changes that need versioning):

    pnpm changeset
    • Follow the prompts to select which packages have changed
    • Choose the appropriate semver increment (patch, minor, major)
    • Write a concise but descriptive message explaining the changes

Testing Your Changes

For testing changes to the core functionality:

  1. Use the examples:

    # Run an example to test your changes
pnpm --filter @example/changesets run start

  2. Create a test-specific example (if needed):

    • Add a new directory in the examples/ folder
    • Implement a minimal reproduction that uses your new feature/fix
    • Run it with pnpm --filter @example/your-example run start

Debugging Tips

When encountering issues during development:

  1. Check for errors in the console - Clack will often output helpful error messages
  2. Review the API documentation - Ensure you're using components and functions as intended
  3. Look at existing examples - See how similar features are implemented
  4. Inspect the packages individually - Sometimes issues are isolated to either core or prompts

Pull Request Process

  1. Commit your changes:

    git add .
git commit -m "feat: add new awesome feature"

  2. Push to your fork:

    git push origin my-feature-branch

  3. Create a pull request:

    • Go to your fork on GitHub
    • Click "New pull request"
    • Select your branch and add a descriptive title
    • Fill in the PR template with details about your changes
    • Reference any related issues

  4. Wait for the automated checks:

    • GitHub Actions will run tests, type checking, and lint validation
    • Fix any issues that arise

  5. Address review feedback:

    • Make requested changes
    • Push additional commits to your branch
    • The PR will update automatically

PR Previews

Clack uses pkg.pr.new (provided by bolt.new) to create continuous preview releases of all PRs. This simplifies testing and makes verifying bug fixes easier for our dependents.

The workflow that builds a preview version and adds instructions for installation as a comment on your PR should run automatically if you have contributed to Clack before. First-time contributors may need to wait until a maintainer manually approves GitHub Actions running on your PR.

Release Process

Clack uses Changesets to manage versions and releases.

  1. For contributors:

    • Create a changeset file with your PR as described above
    • Maintainers will handle the actual release process

  2. For maintainers:

    • Merging PRs with changesets will queue them for the next release
    • When ready to release: 
      # Update versions based on changesets
pnpm ci:version

# Publish to npm
pnpm ci:publish

Backporting to v0 Branch

Clack maintains a stable v0 branch alongside the main development branch. For maintainers who need to backport changes:

  1. Label PRs that should be backported with the backport label
  2. After the PR is merged to main, manually cherry-pick the squashed commit into the v0 branch: 
    # Ensure you have the latest v0 branch
git checkout v0
git pull upstream v0

# Cherry-pick the squashed commit from main
git cherry-pick <commit-hash>

# Push the changes
git push upstream v0
  3. CI is configured to run changesets from the v0 branch, so release PRs will be opened automatically

The GitHub Actions are configured to cut releases from both the main and v0 branches.

Filing Issues

When reporting bugs or requesting features:

  1. Check existing issues to avoid duplicates
  2. Use the issue templates to provide all necessary information
  3. Be specific and clear about what's happening and what you expect
  4. Provide reproduction steps - ideally a minimal example that demonstrates the issue
  5. Include environment details like OS, Node.js version, etc.

Issue Types

When opening an issue, consider which category it falls into:

  • Bug Report: Something isn't working as documented or expected
  • Feature Request: A suggestion for new functionality
  • Documentation Issue: Improvements or corrections to documentation
  • Performance Issue: Problems with speed or resource usage

Style Guide

We use Biome for linting and formatting. Your code should follow these standards:

# To check formatting
pnpm format

# To lint and fix issues automatically where possible
pnpm lint

The project follows standard TypeScript practices. If you're new to TypeScript:

  • Use precise types whenever possible
  • Avoid any unless absolutely necessary
  • Look at existing code for patterns to follow

Commit Message Format

We follow conventional commits for commit messages:

  • feat: - A new feature
  • fix: - A bug fix
  • docs: - Documentation changes
  • style: - Changes that don't affect code functionality (formatting, etc)
  • refactor: - Code changes that neither fix bugs nor add features
  • perf: - Performance improvements
  • test: - Adding or correcting tests
  • chore: - Changes to the build process, tools, etc

License

By contributing, you agree that your contributions will be licensed under the project's MIT License.

Thank you for taking the time to contribute to Clack! Feel free to join our community Discord at bomb.sh/chat. It's a great place to connect with other project contributors—we're chill!

Acknowledgments

This contributing guide was inspired by and adapted from the Astro Contributing Manual. We appreciate their excellent documentation and open source practices.