Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
165 lines (115 loc) · 3.5 KB

CONTRIBUTING.md

File metadata and controls

165 lines (115 loc) · 3.5 KB

Contributing to Padrone

Thank you for your interest in contributing to Padrone! This guide will help you get started.

Getting Started

Prerequisites

  • Bun (v1.0 or later)
  • Node.js 18+ (for compatibility testing)
  • Git

Setup

  1. Fork and clone the repository:

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

  2. Install dependencies:

    bun install

  3. Verify your setup:

    bun run checks

Development Workflow

Project Structure

padrone/
├── packages/padrone/     # Main library
│   ├── src/              # Source code
│   └── tests/            # Tests
├── docs/                 # Documentation site
├── examples/             # Example applications
└── scripts/              # Build scripts

Common Commands

bun run test          # Run tests
bun run check         # Lint and format check
bun run typecheck     # Type checking
bun run checks        # All of the above

Code Style

This project uses Biome for linting and formatting. Key points:

  • Indent: 2 spaces
  • Quotes: Single quotes
  • Line width: 140 characters

Important: Zod imports must use namespace syntax:

import * as z from 'zod/v4';  // Correct

For detailed style guidelines, see AGENTS.md.

Running Tests

# All tests
bun run test

# Single file
bun run test packages/padrone/tests/cli.test.ts

# By pattern
bun run test --test-name-pattern "should parse"

Making Changes

1. Create a Branch

git checkout -b feature/your-feature-name

2. Make Your Changes

  • Write clear, focused commits
  • Add tests for new functionality
  • Update documentation if needed

3. Add a Changeset

When your change should be noted in the changelog, create a changeset:

bun changeset

Follow the prompts to:

  1. Select the padrone package
  2. Choose the version bump type:
    • patch: Bug fixes, docs, internal changes
    • minor: New features, non-breaking enhancements
    • major: Breaking changes
  3. Write a brief summary of your change

This creates a file in .changeset/ that will be included in the next release's changelog.

When to skip changesets:

  • CI/tooling changes only
  • Test-only changes
  • Documentation typos

4. Run Checks

Before committing, ensure all checks pass:

bun run checks

The pre-commit hook will automatically run Biome on staged files.

5. Submit a Pull Request

  1. Push your branch to your fork
  2. Open a PR against main
  3. Fill out the PR template
  4. Wait for CI checks and review

Pull Request Guidelines

  • Keep PRs focused on a single change
  • Write a clear description of what and why
  • Link related issues
  • Respond to review feedback promptly

Releasing a New Version

To release a new version, merge the release PR created by the Changesets. This will trigger the release process, which includes:

  1. Bumping the version based on changesets
  2. Generating a changelog
  3. Publishing to npm

Reporting Issues

  • Search existing issues before creating a new one
  • Use issue templates when available
  • Provide reproduction steps for bugs
  • Include version information

Questions?

License

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