AI Newsletter Digest improvements: fixed QP soft line break decoding, URL extraction, and content cleaning
This commit is contained in:
Krilly
408
skills/openclaw-self-healing/self-healing-github/CONTRIBUTING.md
Normal file
408
skills/openclaw-self-healing/self-healing-github/CONTRIBUTING.md
Normal file
@@ -0,0 +1,408 @@
|
||||
# Contributing to OpenClaw Self-Healing System
|
||||
|
||||
> **Thank you for considering contributing!** Every improvement, bug fix, and documentation update makes this project better for the entire OpenClaw community.
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Ways to Contribute
|
||||
|
||||
### 1. **Bug Reports** 🐛
|
||||
Found something broken? [Open an issue](https://github.com/ramsbaby/openclaw-self-healing/issues/new?template=bug_report.md).
|
||||
|
||||
**Please include:**
|
||||
- macOS version (`sw_vers`)
|
||||
- OpenClaw version (`openclaw version`)
|
||||
- Self-Healing script versions (`head -5 ~/openclaw/scripts/*.sh`)
|
||||
- Relevant logs (last 50 lines of `healthcheck-*.log` or `emergency-recovery-*.log`)
|
||||
- Steps to reproduce
|
||||
|
||||
### 2. **Feature Requests** 💡
|
||||
Have an idea? [Open an issue](https://github.com/ramsbaby/openclaw-self-healing/issues/new?template=feature_request.md).
|
||||
|
||||
**We're especially interested in:**
|
||||
- Linux (systemd) support
|
||||
- Alternative LLM integrations (GPT-4, Gemini, etc.)
|
||||
- Prometheus/Grafana metrics
|
||||
- Additional notification channels (Slack, Telegram, etc.)
|
||||
|
||||
### 3. **Pull Requests** 🔧
|
||||
Code contributions are welcome!
|
||||
|
||||
**Good first PRs:**
|
||||
- Documentation improvements
|
||||
- Bug fixes with test cases
|
||||
- New notification channels
|
||||
- systemd equivalent for Linux
|
||||
|
||||
### 4. **Documentation** 📚
|
||||
Help others by improving docs:
|
||||
- Fix typos or unclear sections
|
||||
- Add examples or tutorials
|
||||
- Translate documentation
|
||||
- Write blog posts/guides
|
||||
|
||||
### 5. **Testing & Validation** 🧪
|
||||
Help verify the system works in different environments:
|
||||
- Test on different macOS versions
|
||||
- Test with different OpenClaw configurations
|
||||
- Test edge cases (network failures, disk full, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
```bash
|
||||
# Clone the repo
|
||||
git clone https://github.com/ramsbaby/openclaw-self-healing.git
|
||||
cd openclaw-self-healing
|
||||
|
||||
# Install dependencies
|
||||
brew install tmux shellcheck
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
|
||||
# Copy environment template
|
||||
cp .env.example ~/.openclaw/.env
|
||||
```
|
||||
|
||||
### Code Style
|
||||
|
||||
**Bash scripts:**
|
||||
- Use `shellcheck` for linting: `shellcheck scripts/*.sh`
|
||||
- 2-space indentation
|
||||
- Meaningful variable names (avoid `$a`, `$b`, etc.)
|
||||
- Add comments for non-obvious logic
|
||||
- Use functions for reusable code
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Good: Clear function name, descriptive variables
|
||||
check_gateway_health() {
|
||||
local gateway_url="$1"
|
||||
local http_code=$(curl -s -o /dev/null -w "%{http_code}" "$gateway_url")
|
||||
|
||||
if [ "$http_code" = "200" ]; then
|
||||
return 0
|
||||
else
|
||||
log "Gateway unhealthy: HTTP $http_code"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Bad: Cryptic, hard to understand
|
||||
chk() {
|
||||
local u="$1"
|
||||
local c=$(curl -s -o /dev/null -w "%{http_code}" "$u")
|
||||
[ "$c" = "200" ] && return 0 || return 1
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔀 Pull Request Process
|
||||
|
||||
### 1. Fork & Branch
|
||||
|
||||
```bash
|
||||
# Fork the repo on GitHub, then:
|
||||
git clone https://github.com/YOUR_USERNAME/openclaw-self-healing.git
|
||||
cd openclaw-self-healing
|
||||
|
||||
# Create a feature branch
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
### 2. Make Changes
|
||||
|
||||
```bash
|
||||
# Edit files
|
||||
nano scripts/gateway-healthcheck.sh
|
||||
|
||||
# Run shellcheck
|
||||
shellcheck scripts/*.sh
|
||||
|
||||
# Test manually
|
||||
bash scripts/gateway-healthcheck.sh
|
||||
```
|
||||
|
||||
### 3. Test Thoroughly
|
||||
|
||||
**Required tests before submitting PR:**
|
||||
|
||||
- [ ] **Level 1 (Watchdog):** Kill Gateway, verify auto-restart
|
||||
- [ ] **Level 2 (Health Check):** Simulate failure, verify retries
|
||||
- [ ] **Level 3 (Claude Recovery):** Inject config error, verify Claude diagnosis
|
||||
- [ ] **Level 4 (Discord Alert):** Simulate Level 3 failure, verify notification
|
||||
|
||||
**Test checklist:**
|
||||
```bash
|
||||
# 1. Kill Gateway
|
||||
kill -9 $(pgrep -f openclaw-gateway)
|
||||
sleep 180
|
||||
curl http://localhost:18789/
|
||||
# Expected: HTTP 200
|
||||
|
||||
# 2. Stop Gateway manually
|
||||
openclaw gateway stop
|
||||
tail -f ~/openclaw/memory/healthcheck-$(date +%Y-%m-%d).log
|
||||
# Expected: Restart attempts
|
||||
|
||||
# 3. Break config (backup first!)
|
||||
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
|
||||
# (edit to break Gateway)
|
||||
# Wait 8 minutes, check Level 3 logs
|
||||
|
||||
# 4. Simulate Level 3 failure
|
||||
# (see TROUBLESHOOTING.md)
|
||||
bash ~/openclaw/scripts/emergency-recovery-monitor.sh
|
||||
# Expected: Discord alert or console output
|
||||
```
|
||||
|
||||
### 4. Commit & Push
|
||||
|
||||
```bash
|
||||
# Stage changes
|
||||
git add scripts/gateway-healthcheck.sh
|
||||
|
||||
# Commit with descriptive message
|
||||
git commit -m "feat: Add configurable retry delay for Health Check
|
||||
|
||||
- Add HEALTH_CHECK_RETRY_DELAY environment variable
|
||||
- Default 30s, configurable via .env
|
||||
- Update documentation with new variable"
|
||||
|
||||
# Push to your fork
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
### 5. Open Pull Request
|
||||
|
||||
Go to GitHub and click "New Pull Request".
|
||||
|
||||
**PR Template:**
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief description of what this PR does.
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Documentation update
|
||||
- [ ] Refactoring
|
||||
|
||||
## Testing
|
||||
- [ ] Tested Level 1 (Watchdog)
|
||||
- [ ] Tested Level 2 (Health Check)
|
||||
- [ ] Tested Level 3 (Claude Recovery)
|
||||
- [ ] Tested Level 4 (Discord Alert)
|
||||
- [ ] Ran shellcheck
|
||||
- [ ] Tested on macOS X.X
|
||||
|
||||
## Screenshots/Logs (if applicable)
|
||||
Paste relevant logs or screenshots here.
|
||||
|
||||
## Checklist
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] Self-reviewed code
|
||||
- [ ] Commented hard-to-understand areas
|
||||
- [ ] Updated documentation
|
||||
- [ ] No breaking changes (or documented)
|
||||
```
|
||||
|
||||
### 6. Code Review
|
||||
|
||||
Maintainers will review your PR. Be responsive to feedback:
|
||||
- Answer questions
|
||||
- Make requested changes
|
||||
- Re-test if needed
|
||||
|
||||
**Review timeline:**
|
||||
- Initial review: 1-3 days
|
||||
- Revisions: As needed
|
||||
- Merge: When approved by 1+ maintainer
|
||||
|
||||
---
|
||||
|
||||
## 📐 Coding Standards
|
||||
|
||||
### Bash Best Practices
|
||||
|
||||
1. **Always quote variables:**
|
||||
```bash
|
||||
# Good
|
||||
if [ "$http_code" = "200" ]; then
|
||||
|
||||
# Bad
|
||||
if [ $http_code = "200" ]; then
|
||||
```
|
||||
|
||||
2. **Use meaningful names:**
|
||||
```bash
|
||||
# Good
|
||||
RECOVERY_TIMEOUT=1800
|
||||
|
||||
# Bad
|
||||
T=1800
|
||||
```
|
||||
|
||||
3. **Check exit codes:**
|
||||
```bash
|
||||
# Good
|
||||
if curl -X POST "$DISCORD_WEBHOOK" ... ; then
|
||||
log "Success"
|
||||
else
|
||||
log "Failed"
|
||||
fi
|
||||
|
||||
# Bad
|
||||
curl -X POST "$DISCORD_WEBHOOK" ...
|
||||
```
|
||||
|
||||
4. **Use functions:**
|
||||
```bash
|
||||
# Good
|
||||
send_discord_notification() {
|
||||
local message="$1"
|
||||
# ... implementation
|
||||
}
|
||||
|
||||
# Bad
|
||||
# Duplicate code multiple times
|
||||
```
|
||||
|
||||
5. **Set exit trap for cleanup:**
|
||||
```bash
|
||||
# Good
|
||||
trap "rm -f $LOCKFILE" EXIT
|
||||
|
||||
# Bad
|
||||
# Forget to cleanup, leave stale locks
|
||||
```
|
||||
|
||||
### Documentation Standards
|
||||
|
||||
1. **Update README.md** if adding/changing features
|
||||
2. **Update QUICKSTART.md** if changing installation
|
||||
3. **Update TROUBLESHOOTING.md** if fixing bugs
|
||||
4. **Add inline comments** for complex logic
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Requirements
|
||||
|
||||
### Unit Tests (Manual)
|
||||
|
||||
```bash
|
||||
# Test individual functions
|
||||
bash -c '
|
||||
source scripts/gateway-healthcheck.sh
|
||||
check_http
|
||||
echo "Exit code: $?"
|
||||
'
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```bash
|
||||
# Test full workflow
|
||||
# 1. Stop Gateway
|
||||
# 2. Wait for Health Check trigger
|
||||
# 3. Verify Level 2 recovery
|
||||
# 4. If Level 3 needed, verify Claude session
|
||||
# 5. Verify Discord notification
|
||||
```
|
||||
|
||||
### Edge Case Tests
|
||||
|
||||
- **Network failure:** Disconnect wifi, verify graceful degradation
|
||||
- **Disk full:** Fill disk, verify logs don't crash system
|
||||
- **Claude quota exhausted:** Verify Level 3 → Level 4 escalation
|
||||
- **Discord webhook invalid:** Verify fallback to console output
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ Commit Message Guidelines
|
||||
|
||||
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
```bash
|
||||
# Format
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
# Types
|
||||
feat: New feature
|
||||
fix: Bug fix
|
||||
docs: Documentation only
|
||||
style: Formatting, missing semicolons, etc.
|
||||
refactor: Code restructuring without changing behavior
|
||||
test: Adding tests
|
||||
chore: Maintenance tasks
|
||||
|
||||
# Examples
|
||||
feat(health-check): Add configurable retry delay
|
||||
fix(emergency-recovery): Handle Claude quota exceeded
|
||||
docs(quickstart): Add macOS 15 compatibility note
|
||||
refactor(discord): Extract notification function
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚧 WIP (Work in Progress) Contributions
|
||||
|
||||
Have an idea but not finished? That's OK!
|
||||
|
||||
1. Open a **Draft PR** on GitHub
|
||||
2. Mark it as **WIP** in the title
|
||||
3. Ask for early feedback
|
||||
4. Convert to regular PR when ready
|
||||
|
||||
---
|
||||
|
||||
## 📜 Code of Conduct
|
||||
|
||||
### Be Respectful
|
||||
|
||||
- Constructive criticism, not personal attacks
|
||||
- Assume good intent
|
||||
- Help others learn
|
||||
|
||||
### Be Patient
|
||||
|
||||
- Maintainers are volunteers
|
||||
- Reviews take time
|
||||
- Not all PRs will be merged (but all are appreciated)
|
||||
|
||||
### Be Collaborative
|
||||
|
||||
- Discuss before major changes
|
||||
- Share knowledge
|
||||
- Credit others' work
|
||||
|
||||
---
|
||||
|
||||
## 🎁 Recognition
|
||||
|
||||
Contributors are recognized in:
|
||||
- **README.md** — "Contributors" section
|
||||
- **CHANGELOG.md** — Release notes
|
||||
- **GitHub Contributors** — Automatic attribution
|
||||
|
||||
---
|
||||
|
||||
## 📞 Questions?
|
||||
|
||||
- **GitHub Discussions:** [github.com/ramsbaby/openclaw-self-healing/discussions](https://github.com/ramsbaby/openclaw-self-healing/discussions)
|
||||
- **OpenClaw Discord:** [discord.com/invite/clawd](https://discord.com/invite/clawd) (mention @ramsbaby)
|
||||
- **Email:** (if urgent, check GitHub profile)
|
||||
|
||||
---
|
||||
|
||||
<p align="center">
|
||||
<strong>Thank you for making OpenClaw Self-Healing better! 🦞</strong>
|
||||
</p>
|
||||
Reference in New Issue
Block a user