PACE Pattern

Appearance

Contributing Guide ​

How to contribute to PACE Pattern and PACE.js.

Welcome Contributors! ​

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

Ways to Contribute ​

1. Report Bugs ​

Found a bug? Please report it!

Before reporting:

  • Search existing issues to avoid duplicates
  • Test with the latest version
  • Gather reproduction steps

Create an issue with:

  • Clear title describing the problem
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, browser, PACE.js version)
  • Minimal code example if possible

Report a bug →

2. Suggest Features ​

Have an idea for PACE? We'd love to hear it!

Before suggesting:

  • Check existing feature requests
  • Consider if it fits PACE philosophy
  • Think through the user experience

Create a feature request with:

  • Clear description of the feature
  • Use cases and benefits
  • Potential implementation approach
  • Examples or mockups if applicable

Request a feature →

3. Improve Documentation ​

Documentation improvements are always welcome!

Types of improvements:

  • Fix typos or unclear wording
  • Add missing information
  • Create tutorials or guides
  • Improve code examples
  • Add diagrams or visuals

How to contribute docs:

  1. Fork pace-site repository
  2. Make your changes in docs/ directory
  3. Preview with npm run docs:dev
  4. Submit a pull request

4. Submit Code ​

Ready to contribute code? Here's how:

Development Setup ​

Prerequisites ​

  • Node.js — v18 or higher
  • npm — v9 or higher
  • Git — Any recent version

Clone the Repository ​

bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/pace-pattern.git
cd pace-pattern

# Add upstream remote
git remote add upstream https://github.com/semanticintent/pace-pattern.git

Install Dependencies ​

bash
npm install

Run Development Server ​

bash
# Start development server with hot reload
npm run dev

# Open http://localhost:5173

Run Tests ​

bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Build ​

bash
# Build for production
npm run build

# Preview production build
npm run preview

Code Standards ​

JavaScript Style ​

We follow StandardJS style:

  • 2 spaces for indentation
  • Single quotes for strings
  • No semicolons (except where required)
  • Descriptive variable names
  • Clear comments for complex logic
javascript
// ✅ Good
function greetUser (user) {
  const expertise = detectExpertise(user.messages)
  const greeting = adaptGreeting(expertise)
  return greeting
}

// ❌ Bad
function greet(u) {
  return "Hello";
}

PACE Philosophy in Code ​

Follow Semantic Intent principles:

1. Clarity Before Code

javascript
// ✅ Good - Clear intent
// Find all products matching the given category
function findProductsByCategory (products, category) {
  return products.filter(product => product.category === category)
}

// ❌ Bad - Unclear intent
function x (a, b) {
  return a.filter(y => y.z === b)
}

2. Intent Before Implementation

Write the "why" in comments, not just the "what":

javascript
// ✅ Good
// Users experience decision paralysis with >7 choices
// Present a curated subset based on conversation context
function selectRelevantProducts (allProducts, context, maxCount = 3) {
  // Implementation...
}

// ❌ Bad
// Select products
function select (p, c, n) {
  // Implementation...
}

3. Natural Language Naming

javascript
// ✅ Good
const userHasExpressedPreference = context.messages.some(
  msg => msg.contains('prefer')
)

// ❌ Bad
const flag = ctx.msgs.some(m => m.has('pref'))

Code Organization ​

src/
├── core/           # Core PACE modules
│   ├── orchestrator.js
│   ├── state-manager.js
│   └── router.js
├── components/     # PACE components
│   ├── product.js
│   ├── about.js
│   ├── chat.js
│   └── executive-summary.js
├── adapters/       # AI adapters
│   ├── claude.js
│   ├── openai.js
│   └── base.js
└── utils/          # Utilities
    ├── dom.js
    └── helpers.js

Testing Requirements ​

All new code must include tests:

javascript
// test/components/chat.test.js
import { describe, it, expect } from 'vitest'
import { Chat } from '../src/components/chat.js'

describe('Chat Component', () => {
  it('should initialize with empty messages', () => {
    const chat = new Chat()
    expect(chat.messages).toEqual([])
  })

  it('should add user message', () => {
    const chat = new Chat()
    chat.addMessage('Hello', 'user')
    expect(chat.messages).toHaveLength(1)
    expect(chat.messages[0].role).toBe('user')
  })
})

Coverage requirements:

  • New features: 80% minimum
  • Bug fixes: Test for the fixed bug
  • Critical paths: 100% coverage

Pull Request Process ​

1. Create a Branch ​

bash
# Update your fork
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

Branch naming:

  • feature/ — New features
  • fix/ — Bug fixes
  • docs/ — Documentation changes
  • refactor/ — Code refactoring
  • test/ — Test improvements

2. Make Your Changes ​

  • Write clear, focused commits
  • Follow code standards
  • Add tests for new features
  • Update documentation if needed

3. Commit Your Changes ​

bash
# Add your changes
git add .

# Commit with descriptive message
git commit -m "feat: Add adaptive complexity to chat component

- Detect user expertise from conversation
- Adjust response complexity accordingly
- Add tests for expertise detection
"

Commit message format:

type: Short description (max 50 chars)

- Bullet point details
- What changed and why
- Reference issues if applicable

Closes #123

Types:

  • feat: — New feature
  • fix: — Bug fix
  • docs: — Documentation
  • refactor: — Code refactoring
  • test: — Test changes
  • chore: — Build/tooling changes

4. Push and Create PR ​

bash
# Push to your fork
git push origin feature/your-feature-name

Then create a pull request on GitHub:

  1. Go to your fork on GitHub
  2. Click "Compare & pull request"
  3. Fill out the PR template
  4. Submit!

PR Template ​

markdown
## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring
- [ ] Other (describe)

## Testing
- [ ] Tests added/updated
- [ ] All tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

## Related Issues
Closes #123
Related to #456

5. Code Review ​

What to expect:

  • Maintainers will review within 3-5 days
  • Feedback will be constructive
  • Changes may be requested
  • Approval required before merge

How to respond:

  • Make requested changes
  • Push to the same branch
  • Respond to review comments
  • Request re-review when ready

Release Process ​

PACE.js follows semantic versioning (semver):

  • Major (1.0.0 → 2.0.0) — Breaking changes
  • Minor (1.0.0 → 1.1.0) — New features, backward compatible
  • Patch (1.0.0 → 1.0.1) — Bug fixes

Releases are managed by maintainers.

Community Guidelines ​

Be Respectful ​

  • Respectful communication
  • Constructive feedback
  • Inclusive language
  • Professional behavior

See Code of Conduct for details.

Ask Questions ​

No question is too simple!

  • GitHub Discussions for general questions
  • Issues for bug reports and features
  • Stack Overflow with pace-pattern tag

Share Knowledge ​

  • Write blog posts
  • Create tutorials
  • Answer questions
  • Help other contributors

Recognition ​

All contributors are recognized:

  • Listed in GitHub contributors
  • Mentioned in release notes
  • Added to documentation credits
  • Featured in community showcase

Need Help? ​

Stuck? Have questions?

Thank You! ​

Your contributions make PACE better for everyone. Thank you for being part of the community! 🙏

Ready to contribute? Find a good first issue →