tendril/CONTRIBUTING.md

# 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)

### Development Environment Setup

**Windows Users with Cursor IDE:**

If you're setting up a Windows development environment with Cursor IDE, see [CURSOR_WINDOWS_SETUP.md](kb/_guides/CURSOR_WINDOWS_SETUP.md) for detailed step-by-step instructions on:
- Installing and configuring the Gitea MCP Server
- Setting up Cursor IDE to work with Gitea
- Configuring authentication tokens
- Testing the connection

### 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.