ra-h-os/CONTRIBUTING.md

Contributing to RA-H

Thank you for your interest in contributing to RA-H! This guide explains how to work inside the private repo that powers the packaged Mac app.

Licensing note: By contributing, you agree that your contributions are provided under the PolyForm Noncommercial License 1.0.0. If you need a commercial exception, contact hello@ra-h.app before submitting changes.

🎯 Ways to Contribute

• 🐛 Bug Reports: Found a bug? Let us know!
• 💡 Feature Requests: Have ideas for new features?
• 📝 Documentation: Help improve our docs
• 🔧 Code Contributions: Fix bugs or implement features
• 🧪 Testing: Help us test new features and find edge cases

🚀 Getting Started

Development Setup

Begin with docs/development/process/0_kickstart.md for internal context. When touching the desktop build, read docs/development/process/6_macpack.md so you follow the packaging checklist. docs/9_open-source.md simply tracks the future BYO-key repo idea; there is no public OSS workflow today.

Development Workflow

Important: We use Claude Code for all development. Follow the 7-step workflow documented in docs/development/process/1_workflow.md:

1. Review - Read handoff and workflow docs
2. Branch - Create feature branch (NEVER work on main)
3. Plan - Write PRD and get approval
4. Implement - Code with user testing
5. Document - Update handoff and CLAUDE.md
6. Commit - Save and merge to main
7. Cleanup - Delete branch, confirm clean state

Quick Commands

# Start new feature
git checkout main && git pull && git checkout -b feature/your-name

# Basic development
npm run build && npm run type-check && npm run lint

# Clean generated artefacts before committing
npm run clean:local

📝 Code Standards

TypeScript

• Use strict TypeScript - no any types unless absolutely necessary
• Provide proper type definitions for all functions and objects
• Use meaningful interface names

React/Next.js

• Use functional components with hooks
• Follow Next.js App Router patterns
• Use proper error boundaries

Database

• All database operations must use the service layer (/src/services/database/)
• No direct SQL in components - use service methods
• Include proper error handling

Styling

• Use Tailwind CSS utilities
• Follow the existing color scheme (dark theme)
• Ensure responsive design

🏗️ Project Architecture

See docs/overview.md for complete system architecture.

Key Patterns

• Use service layer for all database operations
• Components organized by feature area
• Helpers are JSON-configured AI assistants
• All development follows 7-step Claude Code workflow

🧪 Testing

Manual testing is primary - use npm run build && npm run type-check && npm run lint to verify changes.

📚 Documentation

What to Document

• New features and their usage
• API endpoint changes
• Database schema modifications
• Breaking changes

Documentation Style

• Use clear, concise language
• Include code examples
• Add screenshots for UI changes
• Keep README.md updated

🚨 Issue Reporting

Bug Reports

Include:

• Steps to reproduce
• Expected vs actual behavior
• Environment details (OS, Node version, etc.)
• Screenshots if applicable
• Error messages/logs

Feature Requests

Include:

• Clear problem description
• Proposed solution
• Use cases
• Alternatives considered

🔍 Pull Request Process

Before Submitting

• Tests pass locally
• Code follows our style guide
• Documentation updated if needed
• Branch is up to date with main

PR Template

We'll provide a template, but include:

• Description: What does this PR do?
• Type: Bug fix, feature, docs, etc.
• Testing: How was this tested?
• Screenshots: For UI changes

Review Process

1. Automated checks must pass
2. At least one maintainer review required
3. Address feedback promptly
4. Squash commits before merge

🏷️ Labels and Tagging

We use these labels:

• bug - Something isn't working
• enhancement - New feature or request
• documentation - Improvements to docs
• good first issue - Good for newcomers
• help wanted - Extra attention needed
• priority: high/medium/low - Priority levels

💬 Communication

Channels

• Issues: Bug reports and feature requests
• Discussions: General questions and ideas
• Pull Requests: Code review discussions

Code of Conduct

• Be respectful and inclusive
• Focus on constructive feedback
• Help others learn and grow
• Follow our Code of Conduct

🎉 Recognition

Contributors will be:

• Listed in our README acknowledgments
• Mentioned in release notes
• Invited to join our contributors team

📞 Getting Help

Stuck? Need help?

• Check existing issues and discussions
• Create a new discussion for questions
• Tag maintainers in issues if urgent
• Join our community discussions

---

Happy Contributing! 🚀

Your contributions help make RA-H better for everyone. Thank you for being part of our open-source community!