Barry Walker
2c1ed449da
- Implement conventional commits for semantic versioning - PRs: build, test, Docker verify - Merges to main: full release pipeline - Automatic version bump based on commit types - NuGet packaging - Multi-arch Docker build and push to GHCR - Git tag creation - GitHub release Add CONTRIBUTING.md with: - Trunk-based development workflow - Conventional commits guide - Local development instructions
156 lines
3.5 KiB
Markdown
156 lines
3.5 KiB
Markdown
# Contributing to PaperlessMCP
|
|
|
|
Thank you for your interest in contributing! This document outlines our development workflow and guidelines.
|
|
|
|
## Development Workflow
|
|
|
|
We use **trunk-based development**:
|
|
|
|
1. **Create a feature branch** from `main`
|
|
2. **Make your changes** with conventional commits
|
|
3. **Open a pull request** to `main`
|
|
4. **CI runs** build and tests
|
|
5. **Merge to main** triggers automatic release
|
|
|
|
```
|
|
main ←── feature/add-search-filters
|
|
←── fix/upload-timeout
|
|
←── feat/bulk-export
|
|
```
|
|
|
|
## Conventional Commits
|
|
|
|
We use [Conventional Commits](https://www.conventionalcommits.org/) for automatic versioning. Your commit messages determine the version bump:
|
|
|
|
### Commit Format
|
|
|
|
```
|
|
<type>(<scope>): <description>
|
|
|
|
[optional body]
|
|
|
|
[optional footer]
|
|
```
|
|
|
|
### Types and Version Bumps
|
|
|
|
| Type | Description | Version Bump |
|
|
|------|-------------|--------------|
|
|
| `fix:` | Bug fixes | Patch (0.0.X) |
|
|
| `feat:` | New features | Minor (0.X.0) |
|
|
| `feat!:` | Breaking changes | Major (X.0.0) |
|
|
| `docs:` | Documentation only | Patch |
|
|
| `style:` | Code style (formatting) | Patch |
|
|
| `refactor:` | Code refactoring | Patch |
|
|
| `test:` | Adding/updating tests | Patch |
|
|
| `chore:` | Maintenance tasks | Patch |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Bug fix → v1.0.1
|
|
git commit -m "fix: handle null response from API"
|
|
|
|
# New feature → v1.1.0
|
|
git commit -m "feat: add document export functionality"
|
|
|
|
# Breaking change → v2.0.0
|
|
git commit -m "feat!: change API response format"
|
|
|
|
# Or with BREAKING CHANGE footer
|
|
git commit -m "feat: redesign search API
|
|
|
|
BREAKING CHANGE: search now returns paginated results by default"
|
|
```
|
|
|
|
### Scopes (Optional)
|
|
|
|
Use scopes to indicate the affected area:
|
|
|
|
```bash
|
|
git commit -m "fix(upload): increase timeout for large files"
|
|
git commit -m "feat(tags): add bulk delete operation"
|
|
git commit -m "docs(readme): update installation instructions"
|
|
```
|
|
|
|
## Pull Request Process
|
|
|
|
1. **Branch naming**: Use descriptive names
|
|
- `feat/description` for features
|
|
- `fix/description` for bug fixes
|
|
- `docs/description` for documentation
|
|
|
|
2. **PR title**: Use conventional commit format
|
|
- The PR title becomes the merge commit message
|
|
- Example: `feat: add document preview endpoint`
|
|
|
|
3. **Description**: Include
|
|
- What changes were made
|
|
- Why the changes were needed
|
|
- How to test the changes
|
|
|
|
4. **CI checks**: Ensure all checks pass
|
|
- Build succeeds
|
|
- Tests pass
|
|
- Docker builds
|
|
|
|
## Local Development
|
|
|
|
### Prerequisites
|
|
|
|
- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
|
|
- Docker (optional, for container testing)
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Clone the repo
|
|
git clone https://github.com/barryw/PaperlessMCP.git
|
|
cd PaperlessMCP
|
|
|
|
# Restore and build
|
|
dotnet restore
|
|
dotnet build
|
|
|
|
# Run tests
|
|
dotnet test
|
|
```
|
|
|
|
### Running Locally
|
|
|
|
```bash
|
|
# Set environment variables
|
|
export PAPERLESS_BASE_URL=https://your-instance.com
|
|
export PAPERLESS_API_TOKEN=your-token
|
|
|
|
# Run in stdio mode (for testing with Claude)
|
|
dotnet run --project PaperlessMCP/PaperlessMCP -- --stdio
|
|
|
|
# Run in HTTP mode
|
|
dotnet run --project PaperlessMCP/PaperlessMCP
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# All tests
|
|
dotnet test
|
|
|
|
# With verbose output
|
|
dotnet test --logger "console;verbosity=detailed"
|
|
|
|
# Specific test class
|
|
dotnet test --filter "FullyQualifiedName~DocumentToolsTests"
|
|
```
|
|
|
|
## Code Style
|
|
|
|
- Follow existing code patterns
|
|
- Use meaningful variable and method names
|
|
- Add XML documentation for public APIs
|
|
- Keep methods focused and small
|
|
|
|
## Questions?
|
|
|
|
Open an issue for questions or discussions about contributing.
|