“BeeRad”
733d1c3407
Local-first knowledge management system with BYO API keys. Features: - 3-panel UI (Nodes | Focus | Helpers) - SQLite + sqlite-vec for vector search - Agent system (Easy/Hard mode orchestrators) - Content extraction (YouTube, PDF, web) - Integrate workflow for connection discovery - Dimension system with auto-assignment Tech stack: - Next.js 15 + TypeScript + Tailwind CSS - Anthropic (Claude) + OpenAI (GPT) via Vercel AI SDK Setup: npm install && npm rebuild better-sqlite3 scripts/dev/bootstrap-local.sh npm run dev MIT License
174 lines
5.0 KiB
Markdown
174 lines
5.0 KiB
Markdown
# 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](LICENSE). 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
|
|
```bash
|
|
# 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](CODE_OF_CONDUCT.md)
|
|
|
|
## 🎉 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!
|