mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 23:18:24 +00:00
DanConwayDev
93f4cdec7c
Replacement fixtures must not depend on crossing a wall-clock second or finding a lucky lower event ID. The same-second history test previously searched up to 100,000 nonces against a random predecessor, which can still fail when that predecessor has a sufficiently low ID. Add checked timestamp advancement and a re-signing helper that preserves fixture payloads and audit tags. Order recovery announcements after signed deletion cutoffs, repeated announcements after their prior revision, and recovery states after the parked announcement. Use explicit predecessor ordering in sync invitation, ownership replacement and state-fetch tests; remove sleeps whose only purpose was timestamp spacing. Preserve waits that exercise hot-cache expiry and explicit history/conflict timestamps. Return the original audit fixture's signed state through a companion helper without changing its Git commit or existing callers. History revisions can therefore follow that exact initial state. Build two nonce-bearing candidates at one timestamp and sort their IDs to exercise larger-to-smaller replacement and persistence across restart without mining. Document these fixture rules. This changes test construction only. It does not change production event ordering, introduce a shared clock, or import ngit's publishing/mining policy. The caller remains responsible for supplying the relevant predecessor or cutoff; timestamp overflow and signer changes fail explicitly. Validation: recovery and replaceable-history suites, full ngit-grasp suite, all-target workspace Clippy with warnings denied, formatting and diff checks. Assisted-by: GPT-6
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
Deploy ngit-grasp
Problem: Run a durable production relay in a supported hosting environment
You'll learn:
- Choose Docker, NixOS, systemd Linux, Proxmox, or managed hosting
- Preserve the relay identity, Git repositories, and LMDB state
- Configure TLS, verify protocols, back up, and upgrade safely
Upgrade from v2 to v3 Git family storage
Problem: Perform the one-way identifier-family storage migration safely Difficulty: Advanced
You'll learn:
- Prepare capacity and a snapshot-based rollback point
- Run the automatic crash-safe v3 launch migration
- Interpret migration and integrity summary logs
- Restore v2 safely when a release rollback is required
Configure Nix Flakes
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
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
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
- Find your problem - Browse or search for what you need
- Check prerequisites - Make sure you have required knowledge
- Follow the steps - Adapt to your specific situation
- Solve and move on - No need to read everything
Not sure if this is what you need?
- New to ngit-grasp? → Tutorials
- Looking for technical details? → Reference
- Want to understand why? → 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:
# 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 for detailed guidance.
Part of the ngit-grasp documentation using the Diátaxis framework.