From 52bad9954cdddf55ab749fd0c6387edbc766632f Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Tue, 4 Nov 2025 10:25:53 +0000 Subject: docs: use Diátaxis structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 211 ++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 147 insertions(+), 64 deletions(-) (limited to 'docs/README.md') diff --git a/docs/README.md b/docs/README.md index 745211d..ab02cb9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,84 +1,167 @@ # ngit-grasp Documentation -## Overview +Welcome to the **ngit-grasp** documentation! We use the [Diátaxis](https://diataxis.fr/) framework to organize our documentation into four types, each serving a different purpose. + +``` + PRACTICAL THEORETICAL + ───────── ─────────── + +LEARNING │ Tutorials │ Explanation │ + │ │ │ + │ Getting │ Architecture │ + │ Started │ Decisions │ + │ │ │ + ├────────────────┼──────────────────┤ + │ │ │ +WORKING │ How-To │ Reference │ + │ Guides │ │ + │ │ API Docs │ + │ Deployment │ Protocols │ + │ Testing │ │ + │ │ │ +``` + +## 📚 Documentation Types + +### 🎓 [Tutorials](tutorials/) - *Learning by Doing* +**Purpose:** Learn the basics through practical steps +**For:** Newcomers getting started +**Style:** Step-by-step lessons with guaranteed outcomes + +- **[Getting Started](tutorials/getting-started.md)** - Your first ngit-grasp setup +- **[Running Your First Audit](tutorials/first-audit.md)** - Using grasp-audit tool + +### 🔧 [How-To Guides](how-to/) - *Solving Problems* +**Purpose:** Accomplish specific tasks +**For:** Users with basic knowledge solving real problems +**Style:** Practical recipes and solutions + +- **[Deploy ngit-grasp](how-to/deploy.md)** - Production deployment guide +- **[Configure Nix Flakes](how-to/nix-flakes.md)** - Nix development environment +- **[Run Compliance Tests](how-to/test-compliance.md)** - GRASP compliance testing +- **[Upgrade nostr-sdk](how-to/upgrade-nostr-sdk.md)** - Handling SDK upgrades + +### 📖 [Reference](reference/) - *Technical Information* +**Purpose:** Look up technical details +**For:** Users who know what they're looking for +**Style:** Dry, factual, comprehensive + +- **[Git Protocol](reference/git-protocol.md)** - Git Smart HTTP protocol details +- **[GRASP Protocol](reference/grasp-protocol.md)** - GRASP specification details +- **[Configuration](reference/configuration.md)** - All config options +- **[API Reference](reference/api.md)** - Internal API documentation + +### 💡 [Explanation](explanation/) - *Understanding Concepts* +**Purpose:** Understand the "why" and design decisions +**For:** Users wanting deeper understanding +**Style:** Discussion, context, alternatives + +- **[Architecture Overview](explanation/architecture.md)** - System design and components +- **[Inline Authorization](explanation/inline-authorization.md)** - Why we chose this approach +- **[Comparison with ngit-relay](explanation/comparison.md)** - How we differ from reference +- **[Design Decisions](explanation/decisions.md)** - Key architectural choices + +--- -This directory contains comprehensive documentation for the ngit-grasp project. +## 🚀 Quick Start Paths + +### I'm brand new to ngit-grasp +1. Read [README.md](../README.md) for project overview +2. Follow [Getting Started Tutorial](tutorials/getting-started.md) +3. Understand [Architecture Overview](explanation/architecture.md) + +### I want to deploy ngit-grasp +1. Review [Configuration Reference](reference/configuration.md) +2. Follow [Deployment How-To](how-to/deploy.md) +3. Set up monitoring and backups + +### I want to develop on ngit-grasp +1. Follow [Getting Started Tutorial](tutorials/getting-started.md) +2. Read [Architecture Overview](explanation/architecture.md) +3. Check [Nix Flakes How-To](how-to/nix-flakes.md) +4. Review [Test Strategy](how-to/test-compliance.md) + +### I want to understand the design +1. Read [Inline Authorization Explanation](explanation/inline-authorization.md) +2. Review [Design Decisions](explanation/decisions.md) +3. Compare with [ngit-relay Comparison](explanation/comparison.md) + +### I'm looking for specific information +- **Protocol details?** → [Reference](reference/) +- **Configuration options?** → [Configuration Reference](reference/configuration.md) +- **Git protocol?** → [Git Protocol Reference](reference/git-protocol.md) + +--- + +## 📂 Additional Resources + +### [Archive](archive/) +Historical session notes and completed work. Useful for understanding project evolution but not required reading. + +### [Learnings](learnings/) +**DEPRECATED** - Being migrated to Diátaxis structure: +- Gotchas → How-To Guides +- Patterns → Reference or Explanation +- Notes → Appropriate category + +--- + +## 🤝 Contributing to Documentation -## Documents +When adding documentation, ask yourself: -### For Review -- **[../REVIEW_SUMMARY.md](../REVIEW_SUMMARY.md)** - Start here! Executive summary of the architecture investigation and recommendations +**Is it a tutorial?** +- Does it teach a beginner? +- Is it a complete lesson with guaranteed outcome? +- → Add to `tutorials/` -### Architecture & Design -- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Detailed technical architecture, component design, data flows, and implementation details -- **[DECISION_SUMMARY.md](DECISION_SUMMARY.md)** - Why we chose inline authorization over Git hooks -- **[COMPARISON.md](COMPARISON.md)** - Side-by-side comparison with the reference implementation (ngit-relay) +**Is it a how-to guide?** +- Does it solve a specific problem? +- Is it a recipe for accomplishing a task? +- → Add to `how-to/` -### Technical References -- **[GIT_PROTOCOL.md](GIT_PROTOCOL.md)** - Git Smart HTTP protocol reference, pkt-line format, and parsing examples -- **[TEST_STRATEGY.md](TEST_STRATEGY.md)** - Comprehensive testing strategy including reusable GRASP compliance testing tool +**Is it reference material?** +- Is it technical information? +- Will people look it up when needed? +- → Add to `reference/` -### Project Files -- **[../README.md](../README.md)** - Project overview, quick start, and feature list -- **[../.env.example](../.env.example)** - Configuration template -- **[../LICENSE](../LICENSE)** - MIT License +**Is it explanation?** +- Does it explain "why"? +- Does it discuss alternatives or design? +- → Add to `explanation/` -## Reading Guide +See [Diátaxis documentation](https://diataxis.fr/) for more guidance. -### If you want to understand the architecture decision: -1. Read [REVIEW_SUMMARY.md](../REVIEW_SUMMARY.md) - Executive summary -2. Read [DECISION_SUMMARY.md](DECISION_SUMMARY.md) - Detailed rationale -3. Skim [COMPARISON.md](COMPARISON.md) - See how we differ from reference +--- -### If you want to implement: -1. Read [ARCHITECTURE.md](ARCHITECTURE.md) - Component design and code structure -2. Read [TEST_STRATEGY.md](TEST_STRATEGY.md) - Testing approach and compliance tool -3. Read [GIT_PROTOCOL.md](GIT_PROTOCOL.md) - Git protocol details -4. Review code examples in ARCHITECTURE.md +## 📊 Project Status -### If you want to deploy: -1. Read [README.md](../README.md) - Quick start -2. Review [.env.example](../.env.example) - Configuration -3. See deployment section in [ARCHITECTURE.md](ARCHITECTURE.md) +**ALPHA** - Under active development. Core functionality working, API may change. -### If you're comparing with ngit-relay: -1. Read [COMPARISON.md](COMPARISON.md) - Detailed comparison -2. See architecture diagrams in both COMPARISON.md and ARCHITECTURE.md +### Completed +- ✅ grasp-audit compliance testing tool +- ✅ Nix flake development environment +- ✅ nostr-sdk 0.43 upgrade +- ✅ Documentation restructure (Diátaxis) -## Key Concepts +### In Progress +- 🔄 Core ngit-grasp server implementation +- 🔄 GRASP-01 compliance -### Inline Authorization -The core architectural decision: we validate Git pushes **inside the HTTP handler** before spawning Git, rather than using Git's pre-receive hooks. +### Planned +- 🔜 GRASP-02 (Proactive Sync) +- 🔜 GRASP-05 (Archive) -**Benefits:** -- Better error messages (HTTP responses vs. hook stderr) -- Simpler deployment (no hook management) -- Easier testing (pure Rust) -- Better performance (skip Git for invalid pushes) +--- -### GRASP Protocol -Git Relays Authorized via Signed-Nostr Proofs - a protocol for hosting Git repositories with Nostr-based authorization. +## 🔗 External Links -**Key Points:** -- Repository announcements (NIP-34 kind 30317) -- State announcements (NIP-34 kind 30318) -- Multi-maintainer support via recursive maintainer sets -- Push validation against signed state events +- [GRASP Protocol Specification](https://gitworkshop.dev/danconwaydev.com/grasp) +- [NIP-34 (Git Stuff)](https://nips.nostr.com/34) +- [Diátaxis Framework](https://diataxis.fr/) +- [rust-nostr Documentation](https://docs.rs/nostr-sdk/) -### Technology Stack -- **actix-web**: HTTP server -- **git-http-backend**: Git protocol handling (Rust crate) -- **nostr-relay-builder**: Nostr relay infrastructure (rust-nostr) -- **tokio**: Async runtime +--- -## Status - -**ALPHA** - Architecture design complete, implementation not yet started. - -## Contributing - -See [../README.md](../README.md) for contribution guidelines. - -## Questions? - -Open an issue or discussion on the repository. +*Documentation structure based on [Diátaxis](https://diataxis.fr/)* +*Last updated: November 4, 2025* -- cgit v1.2.3