Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Add comprehensive contributing guide and update README

Browse Source 
- 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:
Data Warrior
2025-11-11 10:29:47 -07:00
parent 45fb5530bb
commit cd73dda1f2
2 changed files with 614 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

603
CONTRIBUTING.md Normal file
View 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.

13
README.md
View File

@@ -459,13 +459,22 @@ For issues or questions:
## Contributing ## 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 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 3. Make your changes and test thoroughly
4. Submit a pull request with a clear description 4. Submit a pull request with a clear description
For full details, see [CONTRIBUTING.md](CONTRIBUTING.md).
## Authors ## Authors
- Ryan Parmeter ([@parkingmeter](https://git.parkingmeter.info/parkingmeter)) - Ryan Parmeter ([@parkingmeter](https://git.parkingmeter.info/parkingmeter))