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
This commit is contained in:
603
CONTRIBUTING.md
Normal file
603
CONTRIBUTING.md
Normal file
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user