SyslogSolution/ra-h-os
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: pre-release audit and documentation improvements

Browse Source 
- Simplify CONTRIBUTING.md for open source contributors
- Update version to 0.1.0 (Open Source) in overview
- Clarify BYO-key requirement in UI docs
- Expand open source explanation in docs/9
- Add comprehensive pre-public release audit notes
This commit is contained in:
“BeeRad”
2025-12-24 09:43:51 +11:00
parent 79895100c0
commit 52602a06c4
5 changed files with 237 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+44 -150
View File
@@ -1,173 +1,67 @@
# Contributing to RA-H
# Contributing to RA-H Open Source
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.
This is the **open source mirror** of a private repository. Features are developed privately and synced here periodically.
> **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.
## How to Contribute
## 🎯 Ways to Contribute
### Bug Reports & Feature Requests
Open an [issue](../../issues). Include:
- What you expected vs what happened
- Steps to reproduce (for bugs)
- Your environment (OS, Node version, browser)
- **🐛 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
### Code Contributions
We accept pull requests for:
- **Bug fixes** - especially ones you've encountered
- **Documentation improvements** - typos, clarifications, examples
- **Small enhancements** - that don't require architectural changes
## 🚀 Getting Started
For **larger features**, open an issue first to discuss. Major features are typically implemented in the private repo and synced here.
### 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 Setup
### 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
git clone https://github.com/bradwmorris/ra-h_os.git
cd ra-h_os
npm install
npm rebuild better-sqlite3
scripts/dev/bootstrap-local.sh
npm run dev
```
## 📝 Code Standards
Open http://localhost:3000 and add your API keys.
### TypeScript
- Use strict TypeScript - no `any` types unless absolutely necessary
- Provide proper type definitions for all functions and objects
- Use meaningful interface names
## Before Submitting a PR
### React/Next.js
- Use functional components with hooks
- Follow Next.js App Router patterns
- Use proper error boundaries
```bash
npm run build
npm run type-check
npm run lint
```
### Database
- All database operations must use the service layer (`/src/services/database/`)
- No direct SQL in components - use service methods
- Include proper error handling
All three must pass.
### Styling
- Use Tailwind CSS utilities
- Follow the existing color scheme (dark theme)
- Ensure responsive design
## Code Style
## 🏗️ Project Architecture
- TypeScript with strict types (avoid `any`)
- Functional React components
- Tailwind CSS for styling
- Database operations through service layer (`/src/services/database/`)
See `docs/overview.md` for complete system architecture.
## What Happens to Your Contribution
### 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
1. We review and merge to this repo
2. If applicable, we port the fix to the private repo
3. Future syncs won't overwrite your contribution
## Code of Conduct
## 🧪 Testing
Manual testing is primary - use `npm run build && npm run type-check && npm run lint` to verify changes.
Be respectful. No harassment, trolling, or personal attacks. Focus on constructive feedback.
## 📚 Documentation
## License
### What to Document
- New features and their usage
- API endpoint changes
- Database schema modifications
- Breaking changes
By contributing, you agree your work is licensed under [MIT](LICENSE).
### Documentation Style
- Use clear, concise language
- Include code examples
- Add screenshots for UI changes
- Keep README.md updated
## Questions?
## 🚨 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!
Open a [discussion](../../discussions) or check existing issues.