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
• Development Workflow
• Branch Management
• Documentation Guidelines
• Code Standards
• Submitting Changes
• Documentation Types

Getting Started

Prerequisites

Before you begin, ensure you have:

1. Rust installed (via rustup - required for dev extensions)

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

   git clone https://git.parkingmeter.info/Mycelium/tendril.git
   cd tendril
   

3. Add upstream remote (if you forked):

   git remote add upstream https://git.parkingmeter.info/Mycelium/tendril.git
   

4. Verify setup:

   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:

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

3. Test Your Changes

For Code Changes:

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

# 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

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

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

# 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

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

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

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

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

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

   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:

   git checkout main
   git pull upstream main
   

2. Delete your feature branch (optional):

   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.