workflows-ts/CONTRIBUTING.md

Contributing to workflows-ts

Thank you for your interest in contributing to workflows-ts! This guide will help you get started with contributing to our event-driven workflow engine.

Getting Started

Prerequisites

• Node.js: Version 18 or higher
• pnpm: Version 10.15.0 (managed by packageManager field)
• Git: For version control

Initial Setup

1. Fork and clone the repository

   git clone https://github.com/your-username/workflows-ts.git
   cd workflows-ts
   

2. Install dependencies

   pnpm install
   

3. Build all packages

   pnpm run build
   

4. Run tests to verify setup

   pnpm run test
   

Development Workflow

Project Structure

This is a monorepo with the following key packages:

• packages/core/: Core workflow engine (@llamaindex/workflow-core)
• packages/http/: HTTP protocol adapter (@llamaindex/workflow-http)
• packages/llamaindex/: LlamaIndex integration
• demo/: Example implementations and integrations
• tests/cjs/: CommonJS compatibility tests

Common Development Commands

Monorepo-wide Commands

# Build all packages
pnpm run build

# Type check across all packages
pnpm run typecheck

# Run all tests
pnpm run test

# Check code formatting
pnpm run format

# Auto-format code
pnpm run format:write

# Check linting
pnpm run lint

# Auto-lint code (might still leave linting problems)
pnpm run lint:fix

Package-specific Development

# Core package development
cd packages/core
pnpm run build    # Build the core package
pnpm run dev      # Watch mode for development
pnpm run test     # Run core package tests
pnpm run lint     # Lint
pnpm run lint:fix # Lint and auto-fix errors

# HTTP package development
cd packages/http
pnpm run build    # Build with Bunchee
pnpm run dev      # Watch mode with Bunchee

Making Changes

1. Create a feature branch

   git checkout -b feature/your-feature-name
   

2. Make your changes

   • Follow the existing code style and patterns
   • Add tests for new functionality
   • Update documentation as needed

3. Test your changes

   pnpm run test           # Run all tests
   pnpm run typecheck      # Check TypeScript types
   pnpm run format         # Verify formatting
   pnpm run lint           # Verify linting
   

4. Commit your changes

   git add .
   git commit -m "feat: add your feature description"
   

   We use Husky for pre-commit hooks that will automatically format your code and run checks.

Code Style and Standards

Formatting

• We use Biome for code formatting
• Formatting is automatically applied on commit via lint-staged
• Run pnpm run format:write to format files manually

Linting

• We use Biome for linting
• Running pnpm run lint:fix is a way of auto-linting the code, but it might leave untracked errors

TypeScript

• All code should be written in TypeScript
• Ensure pnpm run typecheck passes before submitting
• Follow existing type patterns and naming conventions

Testing

• Test framework: Vitest
• Browser testing: Uses happy-dom environment
• Test location: Tests should be colocated with source files (.test.ts)
• Write tests for new features and bug fixes
• Maintain or improve test coverage

Submitting Changes

Pull Request Process

1. Push your branch

   git push origin feature/your-feature-name
   

2. Create a Pull Request

   • Use a descriptive title and description
   • Reference any related issues
   • Ensure all CI checks pass

3. Address feedback

   • Respond to code review comments
   • Make requested changes
   • Push updates to your branch

Commit Message Format

We follow conventional commit format:

• feat: new features
• fix: bug fixes
• docs: documentation changes
• style: formatting changes
• refactor: code refactoring
• test: adding or updating tests
• chore: maintenance tasks

Changeset Process

For changes that affect published packages:

1. Create a changeset

   npx changeset
   

2. Follow the prompts to describe your changes and select affected packages

3. Commit the changeset file along with your changes

Release Process

Maintainers only

Releases are managed through Changesets:

• Maintainers will run pnpm run publish to create releases
• Version bumps are determined by changeset files
• Packages are independently versioned and published

Getting Help

• Issues: Check existing issues or create a new one
• Discussions: Use GitHub Discussions for questions
• Documentation can be found at https://ts.llamaindex.ai/docs/workflows

---

Thank you for contributing to workflows-ts! 🚀