Offworld Docs

Thank you for considering contributing to Offworld! This guide will help you get started.

Getting Started

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/offworld.git

Follow Project Setup to get running locally
Create a branch:
```
git checkout -b feature/your-feature
```

Development Workflow

Make your changes

Run quality checks:

bun run check      # Lint + format
bun run typecheck  # Type checking

Test manually (see Development Workflow)
Commit your changes (see Commit Guidelines below)
Push to your fork:
```
git push origin feature/your-feature
```
Open a Pull Request on GitHub

Commit Guidelines

Follow Conventional Commits:

<type>: <description>

[optional body]

Types

feat: - New feature
fix: - Bug fix
refactor: - Code refactoring
docs: - Documentation changes
chore: - Maintenance tasks
test: - Test changes
perf: - Performance improvements

Examples

git commit -m "feat: add difficulty filter to issues tab"
git commit -m "fix: resolve Mermaid diagram rendering bug"
git commit -m "docs: update README with deployment instructions"

Code Style

Linting & Formatting

Biome handles both linting and formatting.

Auto-fix:

bun run check

Config: biome.json (root)

TypeScript

Strict mode enabled
Avoid any - use unknown or proper types
Prefer const over let
Use type inference when possible

React

Functional components with hooks
Use const for components
Extract complex logic to custom hooks
Prefer named exports

Convex Functions

Export with query(), mutation(), or action()
Add input validation with v.object({})
Mark internal functions clearly (prefix _ or in _file.ts)
Document complex queries

Pull Request Guidelines

PR Title

Use conventional commit format:

feat: add difficulty filter to issues tab

PR Description

Include:

What - What changes did you make?
Why - Why were these changes needed?
How - How did you implement it?
Testing - How did you test it?

Example PR Description

## What
Added difficulty filter to issues tab

## Why
Users requested ability to filter issues by difficulty level to find beginner-friendly issues

## How
- Added filter UI in `issues/index.tsx`
- Updated query in `repos.ts` to accept difficulty param
- Added URL param for shareable filtered views

## Testing
- Tested filtering by each difficulty level
- Verified URL params persist on refresh
- Checked mobile responsive design

Before Submitting

Code passes bun run check
Code passes bun run typecheck
Changes tested locally
Documentation updated (if needed)
No console.logs or debug code left

Areas to Contribute

🟢 Good First Issues

Documentation improvements
UI polish (spacing, colors, typography)
Adding missing error messages
Writing tests

🟡 Intermediate

New UI features (filters, sorting)
Additional agent tools
Performance optimizations
Better error handling

🔴 Advanced

Core architecture changes
Workflow improvements
New AI prompts
RAG system enhancements

Check GitHub Issues for current tasks.

Project Structure

offworld/
├── apps/
│   ├── web/              # Frontend
│   └── fumadocs/         # Docs
├── packages/
│   ├── backend/          # Convex backend
│   └── config/           # Shared config

See Architecture for details.

Testing

Currently manual testing (see Development Workflow).

Future: Unit tests, integration tests, E2E tests.

Documentation

When adding features, update:

README.md - If user-facing feature
CLAUDE.md - If architectural change
Fumadocs (apps/fumadocs/content/) - For user guides

Community

GitHub Discussions - Ask questions, share ideas
GitHub Issues - Report bugs, request features
Pull Requests - Contribute code

Code of Conduct

Be respectful, inclusive, and constructive. We're all here to build something great together.

License

By contributing, you agree that your contributions will be licensed under the project's license (see LICENSE file).

Questions?

Open a GitHub Discussion or reach out to @oscabriel.

Next Steps

Check Troubleshooting if you encounter issues
Read Technical Reference for API details

Contributing