Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
178 lines (120 loc) · 4.39 KB

CONTRIBUTING.md

File metadata and controls

178 lines (120 loc) · 4.39 KB

Contributing to js-ai-driven-development-pipeline-template

Development Workflow

  1. Fork the repository and clone your fork
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Install dependencies: bun install (or npm install)
  4. Make your changes
  5. Run local checks: bun run check
  6. Create a changeset: bun run changeset
  7. Commit and push (pre-commit hooks will run automatically)
  8. Create a Pull Request

Code Standards

File Size Limits

Maximum 1000 lines per file (enforced via ESLint).

This benefits both AI and human developers by ensuring files remain readable and maintainable.

Formatting and Linting

All code must pass:

# Check formatting
bun run format:check

# Check linting
bun run lint

# Run all checks
bun run check

The pre-commit hook runs automatically, but you can also manually format and fix:

# Auto-fix formatting
bun run format

# Auto-fix lint issues
bun run lint:fix

Testing Requirements

Tests should:

  • Cover critical paths
  • Work across all runtimes (Node.js, Bun, Deno)
  • Use the test-anywhere framework
# Run tests
bun test
npm test
deno test --allow-read

Version Management with Changesets

This project uses Changesets to manage versions and changelogs. This eliminates merge conflicts that occur when multiple PRs bump the version in package.json.

Adding a Changeset

When you make changes that affect users, add a changeset:

bun run changeset
# or
npm run changeset

This will prompt you to:

  1. Select the type of change (patch/minor/major)
  2. Provide a summary of the changes

The changeset will be saved as a markdown file in .changeset/ and should be committed with your PR.

Changeset Guidelines

Type When to Use Examples
Patch Bug fixes, internal changes Fix typo, update dependency, refactor internal code
Minor New features, non-breaking additions Add new function, new optional parameter
Major Breaking changes Remove function, change API signature

Example changeset summary:

Add support for custom configuration via config file

What Changes Need Changesets?

Required for:

  • Bug fixes
  • New features
  • Breaking changes
  • Public API changes

Not required for:

  • Documentation-only changes (in ./docs folder)
  • Changes to markdown files
  • CI/CD workflow updates (unless they affect users)

Release Process

The release process is fully automated:

  1. PR with changeset merged - The changeset is added to .changeset/
  2. CI detects changesets - On push to main, CI checks for pending changesets
  3. Version bump - Package version is updated based on changeset type
  4. Changelog update - CHANGELOG.md is updated automatically
  5. npm publish - Package is published via OIDC trusted publishing
  6. GitHub Release - A release is created with formatted notes

Multiple Changesets

If multiple PRs are merged before a release:

  • All changesets are merged into one
  • The highest version bump type wins (major > minor > patch)
  • All descriptions are preserved in chronological order

Pull Request Guidelines

PR Title

Use a clear, descriptive title that summarizes the change:

feat: Add support for custom configuration
fix: Resolve race condition in async handler
docs: Update API documentation for v2

PR Description

Include:

  • What - Describe the change
  • Why - Explain the motivation
  • Testing - How the change was tested

CI Checks

All PRs must pass:

  • Changeset validation (for code changes)
  • Lint and format check
  • Tests on all platforms (Ubuntu, macOS, Windows)
  • Tests on all runtimes (Node.js, Bun, Deno)

Fresh Merge Simulation

The CI workflow automatically:

  1. Merges the latest main into your PR branch
  2. Runs checks against the merged state

If this fails with merge conflicts, you need to:

git fetch origin main
git merge origin/main
# Resolve conflicts
git push

Questions?

If you have questions about contributing, feel free to open an issue for discussion.