From cd73dda1f26684dbaf769435c08208a59abb5402 Mon Sep 17 00:00:00 2001
From: Data Warrior <fso@data-warrior.com>
Date: Tue, 11 Nov 2025 10:29:47 -0700
Subject: [PATCH] Docs: Add comprehensive contributing guide and update README

- Add CONTRIBUTING.md with full development workflow documentation
- Document branch naming conventions (feature/, docs/, fix/, etc.)
- Add documentation standards and guidelines
- Establish PR process and review criteria
- Update README.md Contributing section to reference new guide
- Prepare foundation for documentation restructuring work
---
 CONTRIBUTING.md | 603 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  13 +-
 2 files changed, 614 insertions(+), 2 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..11e65be
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,603 @@
+# Contributing to Tendril
+
+Thank you for your interest in contributing to Tendril! This guide will help you understand the development workflow, documentation standards, and how to submit changes.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Branch Management](#branch-management)
+- [Documentation Guidelines](#documentation-guidelines)
+- [Code Standards](#code-standards)
+- [Submitting Changes](#submitting-changes)
+- [Documentation Types](#documentation-types)
+
+## Getting Started
+
+### Prerequisites
+
+Before you begin, ensure you have:
+
+1. **Rust installed** (via rustup - required for dev extensions)
+   ```bash
+   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+   ```
+
+2. **Zed IDE** installed from https://zed.dev
+
+3. **Git** configured with your credentials
+
+4. **Access to the repository** (fork or direct access)
+
+### Repository Setup
+
+1. **Fork the repository** (if you don't have direct write access):
+   - Go to https://git.parkingmeter.info/Mycelium/tendril
+   - Click "Fork" to create your own copy
+
+2. **Clone your fork** (or the main repo if you have access):
+   ```bash
+   git clone https://git.parkingmeter.info/Mycelium/tendril.git
+   cd tendril
+   ```
+
+3. **Add upstream remote** (if you forked):
+   ```bash
+   git remote add upstream https://git.parkingmeter.info/Mycelium/tendril.git
+   ```
+
+4. **Verify setup**:
+   ```bash
+   git remote -v
+   # Should show origin (your fork) and upstream (main repo)
+   ```
+
+## Development Workflow
+
+### 1. Checkout a New Branch
+
+Always create a new branch for your work. Never commit directly to `main`.
+
+**Branch Naming Conventions:**
+
+- `feature/description` - New features (e.g., `feature/http-streaming`)
+- `docs/description` - Documentation updates (e.g., `docs/contributing-guide`)
+- `fix/description` - Bug fixes (e.g., `fix/docker-path-resolution`)
+- `refactor/description` - Code refactoring (e.g., `refactor/error-handling`)
+- `test/description` - Test improvements (e.g., `test/windows-compatibility`)
+
+**Example:**
+```bash
+# Update your local main branch first
+git checkout main
+git pull upstream main  # or: git pull origin main
+
+# Create and checkout a new branch
+git checkout -b feature/your-feature-name
+
+# Or for documentation:
+git checkout -b docs/your-doc-update
+```
+
+### 2. Make Your Changes
+
+Work on your feature, fix, or documentation update.
+
+**For Code Changes:**
+- Edit `src/mcp_server_gitea.rs` for extension logic
+- Edit `extension.toml` for extension metadata
+- Edit `Cargo.toml` for dependencies
+
+**For Documentation:**
+- See [Documentation Guidelines](#documentation-guidelines) below
+
+### 3. Test Your Changes
+
+**For Code Changes:**
+```bash
+# Check for compilation errors
+cargo check
+
+# Run linter
+cargo clippy
+
+# Build release version
+cargo build --release
+
+# Test in Zed:
+# 1. Open Zed
+# 2. Extensions → Install Dev Extension
+# 3. Select the tendril directory
+# 4. Test your changes in Assistant panel
+```
+
+**For Documentation:**
+- Review markdown formatting
+- Check all links work
+- Verify code examples are correct
+- Ensure consistency with existing docs
+
+### 4. Commit Your Changes
+
+Use clear, descriptive commit messages:
+
+```bash
+# Good commit messages:
+git commit -m "Add feature: HTTP streaming transport support"
+git commit -m "Fix: Docker binary path resolution on Windows"
+git commit -m "Docs: Add contributing guide and workflow documentation"
+
+# Bad commit messages:
+git commit -m "fix stuff"
+git commit -m "updates"
+git commit -m "WIP"
+```
+
+**Commit Message Format:**
+```
+Type: Brief description (50 chars or less)
+
+Optional longer explanation if needed. Can wrap to 72 characters.
+Explain what and why, not how.
+
+- Bullet points for multiple changes
+- Reference issues: Fixes #123
+```
+
+**Types:**
+- `Add` - New feature
+- `Fix` - Bug fix
+- `Docs` - Documentation only
+- `Refactor` - Code refactoring
+- `Test` - Test additions/changes
+- `Chore` - Maintenance tasks
+
+### 5. Push Your Branch
+
+```bash
+# Push to your fork
+git push origin feature/your-feature-name
+
+# If branch doesn't exist remotely yet:
+git push -u origin feature/your-feature-name
+```
+
+### 6. Create a Pull Request
+
+1. Go to https://git.parkingmeter.info/Mycelium/tendril
+2. Click "New Pull Request" or "Create Pull Request"
+3. Select your branch
+4. Fill out the PR template:
+
+**PR Title:** Same as your commit message
+
+**PR Description:**
+```markdown
+## Description
+Brief description of what this PR does.
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Refactoring
+- [ ] Other (please describe)
+
+## Changes Made
+- Change 1
+- Change 2
+- Change 3
+
+## Testing
+- [ ] Code compiles: `cargo check`
+- [ ] No clippy warnings: `cargo clippy`
+- [ ] Tested in Zed IDE
+- [ ] Documentation reviewed
+
+## Related Issues
+Closes #123
+Fixes #456
+
+## Screenshots (if applicable)
+[Add screenshots for UI changes]
+
+## Checklist
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] Comments added for complex logic
+- [ ] Documentation updated
+- [ ] No new warnings generated
+- [ ] Tests pass (if applicable)
+```
+
+## Branch Management
+
+### Keeping Your Branch Up to Date
+
+If the main branch has moved forward while you're working:
+
+```bash
+# Switch to main
+git checkout main
+
+# Pull latest changes
+git pull upstream main  # or: git pull origin main
+
+# Switch back to your branch
+git checkout feature/your-feature-name
+
+# Rebase your changes on top of main
+git rebase main
+
+# If conflicts occur, resolve them, then:
+git add .
+git rebase --continue
+
+# Force push (only after rebase)
+git push --force-with-lease origin feature/your-feature-name
+```
+
+**Note:** Only use `--force-with-lease` on your own feature branches. Never force push to `main`.
+
+### Switching Between Branches
+
+```bash
+# List all branches
+git branch -a
+
+# Switch to a branch
+git checkout branch-name
+
+# Create and switch in one command
+git checkout -b new-branch-name
+
+# See what branch you're on
+git branch
+```
+
+## Documentation Guidelines
+
+### Documentation Structure
+
+Tendril has several types of documentation files:
+
+1. **README.md** - Main user-facing documentation
+   - Installation instructions
+   - Configuration examples
+   - Troubleshooting
+   - User-focused content
+
+2. **DEVELOPMENT.md** - Developer guide
+   - Architecture details
+   - Code structure
+   - Development setup
+   - Roadmap
+
+3. **PROJECT_STATUS.md** - Project status and roadmap
+   - Current version status
+   - Completed features
+   - Known issues
+   - Testing status
+
+4. **QUICKSTART.md** - Quick setup guide
+   - TL;DR version
+   - Minimal steps to get started
+
+5. **CONTRIBUTING.md** - This file
+   - Contribution guidelines
+   - Development workflow
+
+6. **Configuration Documentation:**
+   - `configuration/default_settings.jsonc` - Settings template with comments
+   - `configuration/installation_instructions.md` - UI-visible setup guide
+
+7. **Analysis/Research Docs:**
+   - `SSE_MODE_ANALYSIS.md` - Technical decisions
+   - `TESTING_FINDINGS.md` - Test results and learnings
+
+### When to Update Documentation
+
+**Update README.md when:**
+- Adding new configuration options
+- Changing installation steps
+- Adding new features users interact with
+- Fixing common issues
+
+**Update DEVELOPMENT.md when:**
+- Changing code architecture
+- Adding new code patterns
+- Updating development setup
+- Changing build process
+
+**Update PROJECT_STATUS.md when:**
+- Releasing new versions
+- Completing major features
+- Changing project status
+- Updating roadmap
+
+**Create new documentation when:**
+- Making significant technical decisions
+- Documenting test results
+- Explaining complex features
+- Providing detailed guides
+
+### Documentation Standards
+
+1. **Markdown Formatting:**
+   - Use proper heading hierarchy (## for sections, ### for subsections)
+   - Use code blocks with language tags: ` ```bash `, ` ```rust `, ` ```json `
+   - Use tables for structured data
+   - Use lists for step-by-step instructions
+
+2. **Code Examples:**
+   - Always test code examples before committing
+   - Include expected output when relevant
+   - Use realistic examples, not placeholders
+   - Show both success and error cases when helpful
+
+3. **Links:**
+   - Use relative links for internal documentation: `[README](README.md)`
+   - Use absolute links for external resources
+   - Verify all links work before committing
+
+4. **Consistency:**
+   - Follow existing documentation style
+   - Use consistent terminology (e.g., "gitea-mcp" not "gitea mcp")
+   - Match formatting patterns in similar documents
+
+### Creating New Documentation
+
+**For a new feature guide:**
+```bash
+# Create new doc file
+git checkout -b docs/feature-name-guide
+touch FEATURE_NAME.md
+
+# Write documentation following existing patterns
+# Reference it from README.md or appropriate location
+```
+
+**For technical analysis:**
+```bash
+# Create analysis document
+git checkout -b docs/technical-decision-name
+touch TECHNICAL_DECISION.md
+
+# Document:
+# - Problem statement
+# - Options considered
+# - Decision made
+# - Rationale
+# - Implementation details
+```
+
+**Example Documentation Template:**
+```markdown
+# Feature Name / Analysis Title
+
+**Date**: YYYY-MM-DD  
+**Status**: Draft / In Progress / Complete  
+**Related**: Issue #123, PR #456
+
+## Overview
+
+Brief description of what this document covers.
+
+## Details
+
+### Section 1
+Content here.
+
+### Section 2
+More content.
+
+## References
+
+- [Link 1](https://example.com)
+- [Link 2](https://example.com)
+
+## Conclusion
+
+Summary of key points.
+```
+
+## Code Standards
+
+### Rust Code Quality
+
+Before submitting code:
+
+```bash
+# Format code
+cargo fmt
+
+# Check for issues
+cargo check
+
+# Run linter
+cargo clippy
+
+# Build release
+cargo build --release
+```
+
+**Code Style:**
+- Follow Rust naming conventions
+- Keep functions focused (< 50 lines preferred)
+- Add comments for complex logic
+- Use meaningful variable names
+- Handle errors explicitly
+
+### Error Messages
+
+- Be specific about what went wrong
+- Provide actionable solutions
+- Include file paths or commands when relevant
+- Format multi-line errors clearly
+
+### Testing Checklist
+
+Before submitting:
+- [ ] Code compiles: `cargo check`
+- [ ] No clippy warnings: `cargo clippy`
+- [ ] Builds successfully: `cargo build --release`
+- [ ] Tested manually in Zed IDE
+- [ ] Documentation updated if needed
+- [ ] No breaking changes (or documented if intentional)
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Ensure your branch is up to date** (see Branch Management above)
+
+2. **Push your branch:**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+3. **Create Pull Request:**
+   - Go to repository on Gitea
+   - Click "New Pull Request"
+   - Select your branch
+   - Fill out PR description (see template above)
+
+4. **Respond to feedback:**
+   - Address review comments
+   - Make requested changes
+   - Push updates to your branch (PR updates automatically)
+   - Mark conversations as resolved when done
+
+5. **After approval:**
+   - Maintainer will merge your PR
+   - Your branch can be deleted after merge
+
+### PR Review Criteria
+
+Your PR will be reviewed for:
+
+- **Functionality**: Does it work as intended?
+- **Code Quality**: Follows Rust best practices?
+- **Documentation**: Is it documented appropriately?
+- **Testing**: Has it been tested?
+- **Breaking Changes**: Are any breaking changes documented?
+- **Consistency**: Matches existing code style?
+
+### After Your PR is Merged
+
+1. **Update your local main:**
+   ```bash
+   git checkout main
+   git pull upstream main
+   ```
+
+2. **Delete your feature branch** (optional):
+   ```bash
+   git branch -d feature/your-feature-name
+   git push origin --delete feature/your-feature-name
+   ```
+
+## Documentation Types
+
+### User-Facing Documentation
+
+**README.md** - Main entry point
+- Installation instructions
+- Configuration examples
+- Troubleshooting
+- Quick start guide
+
+**QUICKSTART.md** - Fast setup
+- Minimal steps
+- TL;DR version
+- Quick reference
+
+**configuration/installation_instructions.md** - UI guide
+- Shown in Zed extension UI
+- Concise setup steps
+- Links to full docs
+
+### Developer Documentation
+
+**DEVELOPMENT.md** - Developer guide
+- Architecture overview
+- Code structure
+- Development setup
+- Roadmap
+
+**CONTRIBUTING.md** - This file
+- Contribution process
+- Workflow guidelines
+- Standards
+
+**PROJECT_STATUS.md** - Project state
+- Current version
+- Feature status
+- Testing matrix
+- Roadmap
+
+### Technical Documentation
+
+**SSE_MODE_ANALYSIS.md** - Technical decisions
+- Why SSE was removed
+- Alternatives considered
+- Implementation details
+
+**TESTING_FINDINGS.md** - Test results
+- What was tested
+- Results and learnings
+- Recommendations
+
+**ZedExtensions.md** - Research notes
+- Zed extension development
+- MCP integration
+- Reference material
+
+### Configuration Documentation
+
+**configuration/default_settings.jsonc** - Settings template
+- All available options
+- Inline comments
+- Examples
+- Default values
+
+## Getting Help
+
+If you need help:
+
+1. **Check existing documentation:**
+   - README.md for user questions
+   - DEVELOPMENT.md for developer questions
+   - This file for contribution questions
+
+2. **Search issues:**
+   - Check if your question was already asked
+   - Look for similar problems
+
+3. **Ask in issues:**
+   - Open a new issue with your question
+   - Use "Question" label if available
+   - Provide context about what you're trying to do
+
+4. **Contact maintainers:**
+   - @parkingmeter on Gitea
+   - Open a discussion if available
+
+## Code of Conduct
+
+- Be respectful and constructive
+- Focus on the code, not the person
+- Help others learn and improve
+- Follow the project's coding standards
+- Ask questions when unsure
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache License 2.0, the same license as the project.
+
+---
+
+**Thank you for contributing to Tendril!** 🎉
+
+Your contributions help make this project better for everyone.
+
diff --git a/README.md b/README.md
index 3771875..5223c19 100644
--- a/README.md
+++ b/README.md
@@ -459,13 +459,22 @@ For issues or questions:
 
 ## Contributing
 
-Contributions are welcome! Please:
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:
 
+- Development workflow
+- Branch management
+- Documentation standards
+- Code quality requirements
+- Pull request process
+
+**Quick Start:**
 1. Fork the repository
-2. Create a feature branch
+2. Create a feature branch: `git checkout -b feature/your-feature-name`
 3. Make your changes and test thoroughly
 4. Submit a pull request with a clear description
 
+For full details, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Authors
 
 - Ryan Parmeter ([@parkingmeter](https://git.parkingmeter.info/parkingmeter))