Skip to content
Cosella Cosella Engineering Docs

Contributing

Contributing

Section titled “Contributing”

We welcome contributions to Cosella! This guide will help you get started.

Getting Started

Section titled “Getting Started”

1. Fork the Repository

Section titled “1. Fork the Repository”
Terminal window
# Fork on GitHub, then clone
git clone https://github.com/YOUR_USERNAME/cosella.git
cd cosella

2. Set Up Development Environment

Section titled “2. Set Up Development Environment”
Terminal window
# Install dependencies
pnpm install


# Verify setup
pnpm typecheck
pnpm test

3. Create a Branch

Section titled “3. Create a Branch”
Terminal window
git checkout -b feature/my-feature

Development Workflow

Section titled “Development Workflow”

Code Style

Section titled “Code Style”
  • TypeScript: Strict mode enabled
  • ESLint: Enforced via pre-commit hooks
  • Prettier: Automatic formatting on save

Commit Messages

Section titled “Commit Messages”

Follow Conventional Commits:

feat(package-name): short description under 72 chars

Examples:

  • feat(ui): add new Button variant
  • fix(api-client): handle network errors
  • docs(readme): update installation guide

Testing

Section titled “Testing”

Run tests before committing:

Terminal window
# Unit tests
pnpm test


# Type checking
pnpm typecheck


# Linting
pnpm lint

Adding a New Package

Section titled “Adding a New Package”

Use the Plop generator:

Terminal window
pnpm gen package

This creates:

  • packages/my-package/
  • package.json with proper dependencies
  • tsconfig.json extending shared config
  • src/index.ts with exports

Dependency Rules

Section titled “Dependency Rules”

Hard constraints (enforced by ESLint):

  1. Apps may depend on packages — never the reverse
  2. Packages may not depend on sibling apps
  3. packages/ui → packages/tokens only

Adding a UI Component

Section titled “Adding a UI Component”

Use the Plop generator:

Terminal window
pnpm gen component

This creates:

  • packages/ui/src/my-component/MyComponent.tsx
  • packages/ui/src/my-component/MyComponent.test.tsx
  • Export in packages/ui/src/index.ts

Component Guidelines

Section titled “Component Guidelines”
  1. Accessibility: Follow WAI-ARIA patterns
  2. TypeScript: Full type safety
  3. Styling: Use Tailwind classes with design tokens
  4. Testing: Unit tests + Storybook stories

Pull Request Process

Section titled “Pull Request Process”

1. Create Your Changes

Section titled “1. Create Your Changes”
Terminal window
# Make changes
git add .
git commit -m "feat(ui): add new Button variant"

2. Push to Your Fork

Section titled “2. Push to Your Fork”
Terminal window
git push origin feature/my-feature

3. Create a Pull Request

Section titled “3. Create a Pull Request”
  • Title: Follow Conventional Commits
  • Description: Clear explanation of changes
  • Tests: Include test results
  • Screenshots: For UI changes

4. Code Review

Section titled “4. Code Review”
  • Address reviewer feedback
  • Ensure CI passes
  • Get approval from maintainers

5. Merge

Section titled “5. Merge”

Squash and merge to keep history clean.

Documentation

Section titled “Documentation”

Adding Documentation

Section titled “Adding Documentation”

Documentation lives in apps/docs/:

Terminal window
# Add new page
apps/docs/src/content/docs/my-page.mdx

Documentation Style

Section titled “Documentation Style”
  • Clear: Simple, concise language
  • Examples: Code examples for every feature
  • Structure: Logical hierarchy

Getting Help

Section titled “Getting Help”
  • Issues: Report bugs or request features
  • Discussions: Ask questions or share ideas
  • Discord: Real-time chat with the community

Code of Conduct

Section titled “Code of Conduct”
  • Be respectful and inclusive
  • Welcome newcomers
  • Focus on constructive feedback

Guides by Contributor Type

Section titled “Guides by Contributor Type”

Vibecoders (UI-Only Contributors)

Section titled “Vibecoders (UI-Only Contributors)”

If you want to improve the look and feel of Cosella without touching business logic, see the Vibecoder UI Guide. This guide defines exactly which files are safe to modify and provides step-by-step instructions for common UI tasks.

AI Coding Agents

Section titled “AI Coding Agents”

If you are an AI agent (Claude, Copilot, Cursor, Codex, etc.) contributing to Cosella, see the AI Agent Guide. This guide covers architecture constraints, TypeScript rules, testing requirements, and commit conventions that every agent must follow.

Next Steps

Section titled “Next Steps”