Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
180 lines (127 loc) · 4.07 KB

CONTRIBUTING.md

File metadata and controls

180 lines (127 loc) · 4.07 KB

Contributing to Effect Boxes

Thank you for your interest in contributing to Effect Boxes! This guide covers everything you need to get started with development.

Development Setup

Option A: Nix (recommended)

The project includes a flake.nix that provides Bun, Node.js, and all other tools automatically. Nothing else to install.

git clone https://github.com/lloydrichards/proj_effect-boxes.git
cd proj_effect-boxes

# If you use direnv (recommended alongside nix):
direnv allow

# Otherwise, enter the dev shell manually:
nix develop

# Then install dependencies
bun install

Option B: Manual setup

Install these yourself:

  • Bun runtime
  • Node.js 24+
git clone https://github.com/lloydrichards/proj_effect-boxes.git
cd proj_effect-boxes
bun install

Development Commands

# Run tests
bun test

# Run tests in watch mode
bun test --watch

# Type check
bun type-check

# Lint code
bun lint

# Format code
bun format

# Validate documentation
bun docs:check

# Run examples/scratchpad
bun run scratch

Project Structure

src/
├── Box.ts          # Core Box data type and operations
├── Annotation.ts   # Text annotation system
├── Ansi.ts         # ANSI terminal styling
├── Cmd.ts          # Terminal control commands
├── Reactive.ts     # Position tracking for interactive UIs
└── Width.ts        # Text width calculations
tests/
├── box.test.ts     # Core Box tests
├── ansi.test.ts    # ANSI integration tests
└── *.test.ts       # Additional test suites
scratchpad/         # Development playground

Development Workflow

Using the Scratchpad

The scratchpad/ directory is your playground for experimenting with the library:

# Create a test file
touch scratchpad/my-experiment.ts

# Run it
bun run scratchpad/my-experiment.ts

# Clean up when done
rm scratchpad/my-experiment.ts

Running Specific Tests

# Run a single test file
bun test tests/box.test.ts

# Run tests matching a pattern
bun test --grep "alignment"

Testing Guidelines

  • Use regular vitest for pure functions that don't return Effect types
  • Use @effect/vitest for functions that return Effect types
  • Focus on testing mathematical properties and edge cases
  • See existing tests in tests/ for patterns

Code Style

This project uses Biome for linting and formatting. Run bun lint and bun format before committing.

Key conventions:

  • Pure functions with immutable data
  • Use pipe() for function composition
  • Implement Effect interfaces (Pipeable, Equal, Hash) where appropriate
  • All public functions need JSDoc with @example blocks

Generating the Demo GIF

The demo GIF in the README is generated using VHS:

# Install VHS (macOS)
brew install vhs

# Generate the demo GIF
vhs media/demo.tape

Releasing a New Version

This project uses changesets for versioning and publishing.

Adding a Changeset

When making a noteworthy change, add a changeset:

bun changeset

Follow the prompts to:

  1. Select a semver bump type (patch/minor/major)
  2. Describe the change

This creates a markdown file in .changeset/.

Release Process

  1. Commit the changeset along with your code changes
  2. Push to main: CI detects pending changesets and opens a "Version Packages" PR
  3. Merge the release PR: This bumps package.json, updates CHANGELOG.md, and removes consumed changeset files
  4. Automatic publish: After merging, CI publishes to npm automatically
  5. Verify: Check GitHub Actions and npm

Getting Help

  • Review inline TSDoc comments in src/ for API documentation
  • Check the API Reference for module guides
  • Review AGENTS.md for detailed coding patterns (useful for AI assistants)
  • Open an issue for bugs or feature requests