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.
docs/0_overview.md
+3 -3
View File
@@ -23,6 +23,6 @@ For more information, visit [ra-h.app](https://ra-h.app)
## Current Status
- **Version:** Beta (private distribution)
- **Platform:** Web-based (Next.js server)
- **Roadmap:** Native Mac application with user data migration
- **Version:** 0.1.0 (Open Source)
- **Platform:** Web-based (Next.js server, local-only)
- **License:** MIT
docs/6_ui.md
+1 -1
View File
@@ -76,7 +76,7 @@ RA-H uses a fixed 3-panel desktop layout optimized for knowledge work.
3. **Workflows** - Available workflows (integrate)
4. **Logs** - Activity feed (last 100 entries)
5. **Analytics** - Token usage and cost breakdown
6. **API Keys** - Configure Anthropic/OpenAI/Tavily keys (beta ships with embedded keys)
6. **API Keys** - Configure your Anthropic/OpenAI/Tavily keys (required for operation)
**Logs view:**
- Table/action filtering
docs/9_open-source.md
+27 -6
View File
@@ -1,9 +1,30 @@
# RA-H BYO-Key Plan (Future Work)
# RA-H Open Source
The production repo remains private and powers the packaged Mac app. A separate, minimal open-source project will be created later for users who want to run RA-H with their own API keys. That future repo will include:
This is the open source, BYO-key (bring your own API keys) version of RA-H.
1. Basic three-panel UI
2. Local SQLite storage
3. Simple Settings → API Keys experience (no Supabase/subscription backend)
## What's Included
No active work is happening in this repo toward that goal right now. Track progress in `docs/development/prd-private-repo-reset.md`.
- Full three-panel UI (Nodes | Focus | Helpers)
- Local SQLite storage with vector search
- Complete agent system (ra-h, mini-rah, wise-rah)
- All tools and workflows
- Settings panel with API key management
## What's Not Included
- Mac app packaging (Tauri)
- Supabase authentication
- Subscription/payment system
- Auto-updates
## Relationship to Private Repo
This repo is a **mirror** of the private `ra-h` repository. Features are developed privately and synced here periodically.
- **Contributions welcome** - See [CONTRIBUTING.md](../CONTRIBUTING.md)
- **Bug reports** - Open an issue on GitHub
- **Feature requests** - Open an issue; major features are typically built in the private repo first
## Setup
See the main [README.md](../README.md) for installation instructions.
docs/os_docs/2025-12-09-open-source-porting-notes.md
+162
View File
@@ -1,5 +1,167 @@
# RA-H Open Source Porting Notes (2025-12-09)
---
## Pre-Public Release Audit & Recommendations (2025-12-15)
This section documents the security audit findings and open-source best practice recommendations compiled before making the repository public.
### Audit Summary
| Category | Status |
|----------|--------|
| Credentials/API Keys | ✅ Clean - none found |
| Private repo references | ⚠️ 1 issue to fix |
| Supabase remnants | ✅ Clean - properly removed |
| Sensitive business data | ✅ Clean |
| Documentation completeness | ⚠️ Gaps to address |
---
### 🚨 BLOCKING ISSUES (Must Fix Before Public)
#### 1. Stale Reference in `docs/9_open-source.md`
**Line 9** references a non-existent internal doc:
```
Track progress in `docs/development/prd-private-repo-reset.md`.
```
**Fix:** Remove this line or replace with a public tracking mechanism (GitHub Issues).
#### 2. Stale Version in `docs/0_overview.md`
**Line 26** states: `**Version:** Beta (private distribution)`
**Fix:** Update to `**Version:** 0.1.0 (Open Source)`
#### 3. Outdated Key Reference in `docs/6_ui.md`
**Line 79** mentions: `beta ships with embedded keys`
**Fix:** Clarify this refers to the original private beta, not the BYO-key open source version.
---
### 📋 MISSING FILES (Industry Standard for Open Source)
Based on [GitHub's Open Source Guides](https://opensource.guide/starting-a-project/) and [10up Best Practices](https://10up.github.io/Open-Source-Best-Practices/community/), these files are expected:
| File | Purpose | Priority |
|------|---------|----------|
| `CONTRIBUTING.md` | How to contribute, PR process, code style | **High** |
| `CODE_OF_CONDUCT.md` | Community behavior standards ([Contributor Covenant](https://www.contributor-covenant.org/)) | **High** |
| `SECURITY.md` | How to report vulnerabilities privately | **High** |
| `.github/ISSUE_TEMPLATE/` | Bug report & feature request templates | Medium |
| `.github/PULL_REQUEST_TEMPLATE.md` | PR checklist and format | Medium |
| `CHANGELOG.md` | Version history and changes | Medium |
| `docs/TROUBLESHOOTING.md` | Common issues and solutions | Low |
---
### 🔐 SECURITY CHECKLIST
Per [binbash pre-launch checklist](https://medium.com/binbash-inc/open-source-github-repository-pre-launch-checklist-4a52dbbe4af1) and [OpenSSF guidelines](https://github.com/ossf/wg-best-practices-os-developers):
- [ ] **Run secret scanner** - Use [Gitleaks](https://github.com/gitleaks/gitleaks), [TruffleHog](https://github.com/trufflesecurity/trufflehog), or GitHub's built-in secret scanning
- [ ] **Check git history** - Ensure no credentials in commit history (fresh repo helps)
- [ ] **Enable branch protection** - Require PR reviews for `main` branch
- [ ] **Add SECURITY.md** - Define vulnerability reporting process (e.g., security@yourdomain.com or GitHub Security Advisories)
- [ ] **Review dependencies** - Run `npm audit` and document known vulnerabilities
- [ ] **Add .gitignore review** - Ensure `.env*`, credentials, and local configs are excluded
---
### 📚 DOCUMENTATION GAPS
Current docs are technically solid but missing contributor-facing content:
| Gap | Recommendation |
|-----|----------------|
| No contribution guide | Create `CONTRIBUTING.md` with: setup instructions, code style, PR process, testing requirements |
| No API reference | Consider auto-generating from code or adding `docs/api.md` |
| No troubleshooting | Add common issues (SQLite rebuild, key validation errors) |
| No architecture decision records | Optional but helpful for major decisions |
| Numbered doc files unclear | Add `docs/README.md` explaining what each numbered file covers |
---
### 🏗️ RECOMMENDED FILE STRUCTURE
```
ra-h_os/
├── README.md ✅ exists
├── LICENSE ✅ exists (MIT)
├── CONTRIBUTING.md ❌ create
├── CODE_OF_CONDUCT.md ❌ create
├── SECURITY.md ❌ create
├── CHANGELOG.md ❌ create
├── .github/
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.md
│ │ └── feature_request.md
│ └── PULL_REQUEST_TEMPLATE.md
├── docs/
│ ├── README.md ❌ create (index of docs)
│ └── ...existing docs...
└── ...
```
---
### 🔄 PRIVATE-TO-PUBLIC SYNC BEST PRACTICES
Based on [Microsoft ISE's approach](https://devblogs.microsoft.com/ise/synchronizing-multiple-remote-git-repositories/) and [GitLab mirroring docs](https://docs.gitlab.com/user/project/repository/mirror/):
**Current approach (manual sync) is correct for security.** Recommendations:
1. **Document the sync process publicly** - The current reference to private repo workflow docs won't help public contributors understand when features land
2. **Consider a ROADMAP.md** - Let the community know what's coming from the private repo
3. **Tag releases** - Use semantic versioning (v0.1.0, v0.2.0) so users know when syncs happen
4. **Divergence handling** - Document what happens if someone contributes to OS version (does it get merged upstream? Is OS version append-only from private?)
---
### 👥 GOVERNANCE MODEL
For a project of this size with a private upstream, a **BDFL (Benevolent Dictator for Life)** model is appropriate per [Red Hat's governance guide](https://www.redhat.com/en/blog/understanding-open-source-governance-models):
- You maintain final decision authority
- Contributions are welcome but reviewed against private repo direction
- Clear in CONTRIBUTING.md that this is a mirror, not a community-driven fork
---
### 🎯 PRIORITY ACTION ITEMS
**Before going public (blocking):**
1. Fix the 3 stale references listed above
2. Run a secret scanner on the repo
3. Create `SECURITY.md` with vulnerability reporting instructions
4. Create basic `CONTRIBUTING.md`
5. Add `CODE_OF_CONDUCT.md` (use Contributor Covenant template)
**First week after public:**
6. Enable GitHub branch protection on `main`
7. Add issue templates
8. Create `CHANGELOG.md` starting from v0.1.0
9. Add `docs/README.md` explaining the docs structure
**Ongoing:**
10. Document sync cadence with private repo
11. Consider adding CI (linting, type-check) via GitHub Actions
12. Monitor for community contributions and establish response SLA
---
### 📖 REFERENCE SOURCES
- [Starting an Open Source Project - GitHub Guides](https://opensource.guide/starting-a-project/)
- [Open Source Pre-Launch Checklist - binbash](https://medium.com/binbash-inc/open-source-github-repository-pre-launch-checklist-4a52dbbe4af1)
- [README Best Practices - jehna](https://github.com/jehna/readme-best-practices)
- [Building Welcoming Communities - GitHub Guides](https://opensource.guide/building-community/)
- [Leadership and Governance - GitHub Guides](https://opensource.guide/leadership-and-governance/)
- [Understanding Open Source Governance - Red Hat](https://www.redhat.com/en/blog/understanding-open-source-governance-models)
- [Synchronizing Multiple Git Repositories - Microsoft ISE](https://devblogs.microsoft.com/ise/synchronizing-multiple-remote-git-repositories/)
- [OSS Security Checklist - Onboardbase](https://onboardbase.com/blog/oss-security/)
- [CFPB Open Source Template](https://github.com/cfpb/open-source-project-template)
---
## Agent Handover
**What is this repo?** This is `ra-h_os`, the open source mirror of the private `ra-h` application. It's a BYO-key (bring your own API keys) version without Mac packaging, Supabase auth, or subscription features.