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/tutorials/README.md | 116 ++++++++++++++++ docs/tutorials/first-audit.md | 270 ++++++++++++++++++++++++++++++++++++++ docs/tutorials/getting-started.md | 209 +++++++++++++++++++++++++++++ 3 files changed, 595 insertions(+) create mode 100644 docs/tutorials/README.md create mode 100644 docs/tutorials/first-audit.md create mode 100644 docs/tutorials/getting-started.md (limited to 'docs/tutorials') diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md new file mode 100644 index 0000000..3eb0c5c --- /dev/null +++ b/docs/tutorials/README.md @@ -0,0 +1,116 @@ +# Tutorials + +**Learning-oriented documentation** - Learn by doing with step-by-step guidance. + +--- + +## What Are Tutorials? + +Tutorials are **lessons** that teach you how to use ngit-grasp through practical, hands-on steps. + +**Characteristics:** +- ✅ Learning-oriented (teach beginners) +- ✅ Practical (you follow along) +- ✅ Step-by-step with guaranteed outcomes +- ✅ Complete from start to finish +- ✅ Safe to experiment with + +**Not tutorials:** +- ❌ Problem-solving guides (those are How-To) +- ❌ Technical references (those are Reference) +- ❌ Conceptual explanations (those are Explanation) + +--- + +## Available Tutorials + +### [Getting Started](getting-started.md) +**Time:** 15-20 minutes +**Learn:** Set up ngit-grasp development environment, build and test the code + +**You'll accomplish:** +- Clone and build the project +- Set up Nix development environment +- Run tests successfully +- Understand project structure + +**Start here if:** You're brand new to ngit-grasp + +--- + +### [Running Your First Audit](first-audit.md) +**Time:** 10-15 minutes +**Prerequisites:** [Getting Started](getting-started.md) completed +**Learn:** Use grasp-audit to check GRASP compliance + +**You'll accomplish:** +- Run compliance tests against a relay +- Interpret audit results +- Use the audit tool library +- Understand GRASP requirements + +**Start here if:** You want to test GRASP compliance + +--- + +## Planned Tutorials + +### Deploying Your First GRASP Relay +**Status:** 🔜 Planned (waiting for main server implementation) + +**You'll learn:** +- Deploy ngit-grasp to production +- Configure for your domain +- Set up HTTPS with reverse proxy +- Create your first repository + +--- + +### Contributing Your First PR +**Status:** 🔜 Planned + +**You'll learn:** +- Find an issue to work on +- Set up development environment +- Make changes and test +- Submit a pull request + +--- + +## How to Use Tutorials + +1. **Follow in order** - Each step builds on previous ones +2. **Actually do the steps** - Don't just read, type the commands +3. **Expect success** - If something fails, check troubleshooting +4. **Learn by doing** - Understanding comes from practice + +**Not sure if this is what you need?** +- Want to solve a specific problem? → [How-To Guides](../how-to/) +- Looking for technical details? → [Reference](../reference/) +- Want to understand the design? → [Explanation](../explanation/) + +--- + +## Contributing Tutorials + +When writing a tutorial: + +**DO:** +- ✅ Start with a clear learning goal +- ✅ Provide complete, tested steps +- ✅ Include expected output +- ✅ Add troubleshooting section +- ✅ Keep it focused (one topic) +- ✅ Test with a beginner + +**DON'T:** +- ❌ Assume prior knowledge (or state prerequisites clearly) +- ❌ Skip steps ("obviously you would...") +- ❌ Explain every detail (link to Explanation docs) +- ❌ Try to cover everything (keep scope small) + +See [Diátaxis: Tutorials](https://diataxis.fr/tutorials/) for detailed guidance. + +--- + +*Part of the [ngit-grasp documentation](../README.md) using the [Diátaxis](https://diataxis.fr/) framework.* diff --git a/docs/tutorials/first-audit.md b/docs/tutorials/first-audit.md new file mode 100644 index 0000000..194a976 --- /dev/null +++ b/docs/tutorials/first-audit.md @@ -0,0 +1,270 @@ +# Tutorial: Running Your First GRASP Audit + +**Purpose:** Learn how to use grasp-audit to check GRASP compliance +**Time:** 10-15 minutes +**Prerequisites:** [Getting Started Tutorial](getting-started.md) completed + +--- + +## What You'll Learn + +By the end of this tutorial, you will: +- ✅ Understand what GRASP compliance means +- ✅ Run a compliance audit against a relay +- ✅ Interpret audit results +- ✅ Know how to use the audit tool in your own projects + +--- + +## Step 1: Understanding GRASP Compliance + +GRASP (Git Relays Authorized via Signed-Nostr Proofs) defines requirements for Git hosting with Nostr authorization. + +**Key compliance areas:** +- **NIP-01**: Basic Nostr relay functionality +- **NIP-34**: Git repository events (kind 30317, 30318) +- **Git HTTP**: Smart HTTP protocol support +- **Authorization**: Push validation against state events + +The `grasp-audit` tool verifies all of these automatically. + +--- + +## Step 2: Start a Test Relay + +For this tutorial, we'll use a standard Nostr relay: + +```bash +# In a separate terminal window: +docker run --rm -p 7000:7000 scsibug/nostr-rs-relay + +# Keep this running throughout the tutorial +``` + +**What this does:** Starts a NIP-01 compliant Nostr relay on port 7000. + +**Note:** This relay doesn't fully implement GRASP (no Git hosting), but we can test the Nostr parts. + +--- + +## Step 3: Run the Audit Tool + +Navigate to the grasp-audit directory and run: + +```bash +cd grasp-audit +nix develop + +# Run the integration tests (which include audits) +cargo test --ignored -- --test-threads=1 +``` + +**What you'll see:** +``` +running 3 tests +test tests::test_isolation_basic ... ok +test tests::test_isolation_cleanup ... ok +test tests::test_isolation_concurrent ... ok + +test result: ok. 3 passed; 0 failed; 0 ignored +``` + +**What just happened?** The audit tool: +1. Connected to the relay on port 7000 +2. Checked NIP-01 compliance (event submission, retrieval) +3. Tested isolation between test runs +4. Verified cleanup mechanisms + +--- + +## Step 4: Use the Audit Library + +Let's write a simple audit script. Create a new file: + +```bash +# From grasp-audit directory +cat > examples/my_audit.rs << 'EOF' +use grasp_audit::prelude::*; + +#[tokio::main] +async fn main() -> Result<(), Box> { + // Create an audit client + let client = AuditClient::new("ws://localhost:7000").await?; + + println!("✅ Connected to relay"); + + // Test basic event submission + let test_event = client.create_test_event("Hello GRASP!").await?; + println!("✅ Created test event: {}", test_event.id); + + // Verify we can retrieve it + let retrieved = client.get_event(&test_event.id).await?; + println!("✅ Retrieved event successfully"); + + println!("\n🎉 Basic audit passed!"); + + Ok(()) +} +EOF +``` + +**Note:** This is a simplified example. The actual audit tool has more sophisticated checks. + +--- + +## Step 5: Understanding Audit Results + +When audits fail, you'll see detailed error messages: + +```rust +// Example failure output: +Error: GRASP-01 compliance failed + - NIP-01: ✅ PASS + - NIP-34 kind 30317: ❌ FAIL - Relay rejected repository announcement + - NIP-34 kind 30318: ❌ FAIL - Relay rejected state event + - Git HTTP: ❌ NOT TESTED - No Git endpoint found +``` + +**How to interpret:** +- ✅ **PASS**: Feature works correctly +- ❌ **FAIL**: Feature broken or missing +- ⚠️ **PARTIAL**: Works but with issues +- ⏭️ **SKIPPED**: Couldn't test (dependency failed) + +--- + +## Step 6: Audit a GRASP-Compliant Relay + +To audit a real GRASP relay (when available): + +```bash +# Example (relay doesn't exist yet): +cargo run --bin grasp-audit -- --relay wss://gitnostr.com + +# Or use the library: +let client = AuditClient::new("wss://gitnostr.com").await?; +let results = client.run_full_audit().await?; +println!("{}", results.summary()); +``` + +**What this would check:** +- Nostr relay functionality (NIP-01) +- Git event acceptance (NIP-34) +- Git HTTP endpoint availability +- Push authorization logic +- Multi-maintainer support + +--- + +## Step 7: Automated Testing + +The audit tool is designed for CI/CD integration: + +```bash +# Run all tests (unit + integration) +cargo test --all + +# Run only integration tests +cargo test --ignored + +# Generate coverage report +cargo tarpaulin --ignored --out Html +``` + +**Use in CI:** +```yaml +# Example GitHub Actions +- name: Run GRASP Compliance Tests + run: | + docker run -d -p 7000:7000 scsibug/nostr-rs-relay + cd grasp-audit + cargo test --ignored +``` + +--- + +## What You've Accomplished + +Congratulations! You now: + +✅ Understand GRASP compliance requirements +✅ Can run the audit tool against a relay +✅ Know how to interpret audit results +✅ Can integrate audits into your workflow + +--- + +## Next Steps + +### Learn more about testing: +- Read [Compliance Testing How-To](../how-to/test-compliance.md) +- Review [Test Strategy](../reference/test-strategy.md) + +### Understand the protocols: +- Read [GRASP Protocol Reference](../reference/grasp-protocol.md) +- Review [Git Protocol Reference](../reference/git-protocol.md) + +### Contribute to grasp-audit: +- Check open issues +- Add new compliance checks +- Improve error messages + +--- + +## Troubleshooting + +### "Connection refused" errors +- Make sure the relay is running: `docker ps` +- Check the port: `netstat -an | grep 7000` +- Verify the URL: `ws://localhost:7000` (not `wss://`) + +### Tests timeout +- Relay might be slow to start +- Try running tests again after 5 seconds +- Check Docker logs: `docker logs ` + +### "Event rejected" errors +- Expected for non-GRASP relays +- The relay might not support NIP-34 +- This is normal for the tutorial relay + +--- + +## Deep Dive: How Audits Work + +The audit tool uses **isolated test environments**: + +```rust +// Each test gets a unique identifier +let isolation = IsolationContext::new("my-test"); + +// Events are tagged with this identifier +let event = isolation.create_event("test content").await?; + +// Cleanup removes only this test's events +isolation.cleanup().await?; +``` + +**Why isolation matters:** +- Tests don't interfere with each other +- Can run tests in parallel +- Easy cleanup (no leftover data) + +See [Test Strategy Reference](../reference/test-strategy.md) for details. + +--- + +## Summary + +You've learned how to: +- Run GRASP compliance audits +- Interpret audit results +- Use the audit library +- Integrate audits into testing workflows + +**Next tutorial:** [Deploying ngit-grasp](../how-to/deploy.md) (when main server is ready) + +--- + +*Part of the [ngit-grasp tutorials](./)* +*Previous: [Getting Started](getting-started.md)* diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md new file mode 100644 index 0000000..1a56985 --- /dev/null +++ b/docs/tutorials/getting-started.md @@ -0,0 +1,209 @@ +# Tutorial: Getting Started with ngit-grasp + +**Purpose:** Learn the basics of ngit-grasp through hands-on setup +**Time:** 15-20 minutes +**Prerequisites:** Basic Git and command-line knowledge + +--- + +## What You'll Learn + +By the end of this tutorial, you will: +- ✅ Have a working ngit-grasp development environment +- ✅ Understand the basic project structure +- ✅ Run the test suite successfully +- ✅ Know where to go next + +--- + +## Step 1: Clone the Repository + +First, get the source code: + +```bash +git clone https://gitworkshop.dev/ngit-grasp +cd ngit-grasp +``` + +**What just happened?** You cloned the ngit-grasp repository from the GRASP-enabled Git server. + +--- + +## Step 2: Set Up Nix Development Environment + +ngit-grasp uses Nix flakes for reproducible development environments. + +```bash +# Enter the development environment +nix develop + +# You should see a new shell with all dependencies available +``` + +**What just happened?** Nix read `flake.nix` and created a shell with: +- Rust toolchain (cargo, rustc) +- Git +- All required system libraries + +**Tip:** If `nix develop` doesn't work, you might be using an old Nix version. See the [Nix Flakes How-To](../how-to/nix-flakes.md) for help. + +--- + +## Step 3: Explore the Project Structure + +Take a look around: + +```bash +# View the project structure +ls -la + +# Key directories: +# - src/ - Main ngit-grasp source code (coming soon) +# - grasp-audit/ - Compliance testing tool (working) +# - docs/ - Documentation (you are here!) +``` + +**What you're seeing:** +- `grasp-audit/` is a **subproject** with its own Cargo workspace +- Main ngit-grasp server implementation is planned but not yet started +- Documentation uses Diátaxis framework (tutorials, how-to, reference, explanation) + +--- + +## Step 4: Work with grasp-audit + +The compliance testing tool is the first working component. Let's try it: + +```bash +# Navigate to grasp-audit +cd grasp-audit + +# Enter its development environment +nix develop + +# Build the project +cargo build + +# Run unit tests +cargo test +``` + +**What just happened?** +- `grasp-audit` has its own `flake.nix` for isolated dependencies +- Unit tests run without external dependencies +- Integration tests (marked `#[ignore]`) require a Nostr relay + +--- + +## Step 5: Run Your First Audit (Optional) + +If you want to try the audit tool against a real relay: + +```bash +# In a separate terminal, start a test relay: +docker run --rm -p 7000:7000 scsibug/nostr-rs-relay + +# Back in grasp-audit directory: +cargo test --ignored -- --test-threads=1 +``` + +**What just happened?** Integration tests connected to the relay on port 7000 and verified GRASP compliance. + +**Note:** This step is optional. The relay must be running for these tests to pass. + +--- + +## Step 6: Explore the Code + +Let's look at a simple example: + +```bash +# From grasp-audit directory +cat examples/simple_audit.rs +``` + +This shows how to use the `grasp-audit` library to check GRASP compliance. + +--- + +## Step 7: Read the Documentation + +Now that you have a working setup, explore the documentation: + +```bash +# From project root +cd .. +ls docs/ +``` + +**Recommended reading order:** +1. [Architecture Overview](../explanation/architecture.md) - Understand the design +2. [Inline Authorization](../explanation/inline-authorization.md) - Key decision +3. [Git Protocol Reference](../reference/git-protocol.md) - Technical details + +--- + +## What You've Accomplished + +Congratulations! You now have: + +✅ A working Nix development environment +✅ Built and tested the grasp-audit tool +✅ Understanding of the project structure +✅ Knowledge of where to find more information + +--- + +## Next Steps + +### If you want to contribute: +1. Read [Architecture Overview](../explanation/architecture.md) +2. Check open issues on the repository +3. Review [Design Decisions](../explanation/decisions.md) + +### If you want to deploy: +1. Follow [Deployment How-To](../how-to/deploy.md) +2. Review [Configuration Reference](../reference/configuration.md) + +### If you want to understand GRASP: +1. Read [GRASP Protocol Reference](../reference/grasp-protocol.md) +2. Review [Comparison with ngit-relay](../explanation/comparison.md) + +### If you want to run compliance tests: +1. Follow [Running Your First Audit Tutorial](first-audit.md) +2. Review [Compliance Testing How-To](../how-to/test-compliance.md) + +--- + +## Troubleshooting + +### "nix develop" doesn't work +- You might need Nix with flakes enabled +- See [Nix Flakes How-To](../how-to/nix-flakes.md) + +### Build errors in grasp-audit +- Make sure you're in the `grasp-audit` directory +- Run `nix develop` first +- Check that you have network access (Cargo needs to download crates) + +### Tests fail +- Unit tests should always pass +- Integration tests (`--ignored`) require a relay on port 7000 +- Use `--test-threads=1` for integration tests + +--- + +## Summary + +You've successfully set up ngit-grasp and learned: +- How to use Nix flakes for development +- The project structure (main server + grasp-audit tool) +- How to build and test the code +- Where to find documentation + +**Ready for more?** Try the [First Audit Tutorial](first-audit.md) next! + +--- + +*Part of the [ngit-grasp tutorials](./)* +*Next: [Running Your First Audit](first-audit.md)* -- cgit v1.2.3