mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 15:08:24 +00:00
DanConwayDev
92a9a3bfe0
Move migration guide and scripts to docs/archive/2026-01-relay-ngit-dev-migration/ with clear warnings that these are reference-only materials from a specific migration context, not general-purpose tools. These materials document the relay.ngit.dev migration from ngit-relay to ngit-grasp in January 2026. The scripts were developed iteratively during the migration and are specific to that context. They are preserved for: - Historical reference - Context for production fixes in this branch - Inspiration for future migrations (not direct reuse) The migration uncovered critical bugs now fixed in this branch: - Git protocol error handling - Naughty list false positives - Purgatory event tracking - Sync startup issues - Configuration management
178 lines
3.8 KiB
Markdown
178 lines
3.8 KiB
Markdown
# How-To Guides
|
|
|
|
**Task-oriented documentation** - Practical solutions to common problems.
|
|
|
|
---
|
|
|
|
## What Are How-To Guides?
|
|
|
|
How-to guides are **recipes** that show you how to solve specific problems or accomplish particular tasks.
|
|
|
|
**Characteristics:**
|
|
- ✅ Task-oriented (solve a problem)
|
|
- ✅ Practical (actionable steps)
|
|
- ✅ Assume basic knowledge
|
|
- ✅ Focus on results
|
|
- ✅ Can be followed in any order
|
|
|
|
**Not how-to guides:**
|
|
- ❌ Complete lessons for beginners (those are Tutorials)
|
|
- ❌ Technical specifications (those are Reference)
|
|
- ❌ Conceptual discussions (those are Explanation)
|
|
|
|
---
|
|
|
|
## Available How-To Guides
|
|
|
|
### [Configure Nix Flakes](nix-flakes.md)
|
|
**Problem:** Set up reproducible development environment
|
|
**Difficulty:** Intermediate
|
|
|
|
**You'll learn:**
|
|
- Enable Nix flakes
|
|
- Enter development environment
|
|
- Work with subprojects
|
|
- Troubleshoot common issues
|
|
|
|
---
|
|
|
|
### [Test Sync Against Production Data](production-sync-testing.md)
|
|
**Problem:** Debug and improve sync using real-world data
|
|
**Difficulty:** Intermediate
|
|
|
|
**You'll learn:**
|
|
- Run sync against production relays
|
|
- Sanitize logs for LLM analysis
|
|
- Identify common issues and patterns
|
|
- Iteratively improve sync behavior
|
|
|
|
---
|
|
|
|
## Planned How-To Guides
|
|
|
|
### Deploy ngit-grasp
|
|
**Status:** 🔜 Planned (waiting for main server)
|
|
|
|
**Problem:** Deploy to production
|
|
**You'll learn:**
|
|
- Server requirements
|
|
- Reverse proxy setup (nginx/Caddy)
|
|
- SSL/TLS configuration
|
|
- Monitoring and logging
|
|
|
|
---
|
|
|
|
### Run Compliance Tests
|
|
**Status:** 🔜 Planned
|
|
|
|
**Problem:** Test GRASP compliance
|
|
**You'll learn:**
|
|
- Set up test relay
|
|
- Run integration tests
|
|
- Interpret results
|
|
- Add custom tests
|
|
|
|
---
|
|
|
|
### Upgrade nostr-sdk
|
|
**Status:** 🔜 Planned
|
|
|
|
**Problem:** Handle breaking changes in nostr-sdk
|
|
**You'll learn:**
|
|
- Check for breaking changes
|
|
- Update dependencies
|
|
- Fix compilation errors
|
|
- Test after upgrade
|
|
|
|
---
|
|
|
|
### Configure Authentication
|
|
**Status:** 🔜 Planned (feature not yet implemented)
|
|
|
|
**Problem:** Secure your relay
|
|
**You'll learn:**
|
|
- Enable authentication
|
|
- Configure allowed users
|
|
- Set up rate limiting
|
|
- Monitor access
|
|
|
|
---
|
|
|
|
### Backup and Restore
|
|
**Status:** 🔜 Planned
|
|
|
|
**Problem:** Protect your data
|
|
**You'll learn:**
|
|
- Backup Git repositories
|
|
- Backup Nostr events
|
|
- Restore from backup
|
|
- Automate backups
|
|
|
|
---
|
|
|
|
## How to Use How-To Guides
|
|
|
|
1. **Find your problem** - Browse or search for what you need
|
|
2. **Check prerequisites** - Make sure you have required knowledge
|
|
3. **Follow the steps** - Adapt to your specific situation
|
|
4. **Solve and move on** - No need to read everything
|
|
|
|
**Not sure if this is what you need?**
|
|
- New to ngit-grasp? → [Tutorials](../tutorials/)
|
|
- Looking for technical details? → [Reference](../reference/)
|
|
- Want to understand why? → [Explanation](../explanation/)
|
|
|
|
---
|
|
|
|
## Contributing How-To Guides
|
|
|
|
When writing a how-to guide:
|
|
|
|
**DO:**
|
|
- ✅ Start with the problem/goal
|
|
- ✅ List prerequisites clearly
|
|
- ✅ Provide concrete steps
|
|
- ✅ Include troubleshooting
|
|
- ✅ Show examples
|
|
- ✅ Link to related docs
|
|
|
|
**DON'T:**
|
|
- ❌ Teach basics (link to Tutorials)
|
|
- ❌ Explain every concept (link to Explanation)
|
|
- ❌ List all options (link to Reference)
|
|
- ❌ Make it a tutorial (stay focused on the task)
|
|
|
|
**Template:**
|
|
```markdown
|
|
# How-To: [Task/Problem]
|
|
|
|
**Problem:** [What you're trying to accomplish]
|
|
**Difficulty:** [Beginner/Intermediate/Advanced]
|
|
**Time:** [Estimated time]
|
|
|
|
## Prerequisites
|
|
- [Required knowledge/tools]
|
|
|
|
## Solution
|
|
|
|
### Step 1: [Action]
|
|
[Instructions]
|
|
|
|
### Step 2: [Action]
|
|
[Instructions]
|
|
|
|
## Troubleshooting
|
|
|
|
### [Common problem]
|
|
**Solution:** [How to fix]
|
|
|
|
## Related Documentation
|
|
- [Links to relevant docs]
|
|
```
|
|
|
|
See [Diátaxis: How-To Guides](https://diataxis.fr/how-to-guides/) for detailed guidance.
|
|
|
|
---
|
|
|
|
*Part of the [ngit-grasp documentation](../README.md) using the [Diátaxis](https://diataxis.fr/) framework.*
|