docs: add comprehensive conventional commits and semantic-release guide

- Update CONTRIBUTING.md with full conventional commits specification - Add versioning and release automation section - Update AGENTIC_CODING.md with detailed commit format guide - Update .github/copilot-instructions.md with commit rules for AI agents - Add examples and version bump explanations - Document semantic-release automation process Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
2026-02-08 07:55:03 +00:00
parent 6437f01434
commit d2d4f113d0
3 changed files with 298 additions and 18 deletions
@@ -105,10 +105,88 @@ DocuElevate is an intelligent document processing system that automates handling

 ### Git Workflow
 - Write clear, descriptive commit messages
+- **ALWAYS follow Conventional Commits format** (see below)
 - Keep commits focused and atomic
 - Run tests and linters before committing
 - Pre-commit hooks are configured (`.pre-commit-config.yaml`)
- Follow conventional commits format when appropriate
+
+## Conventional Commits (REQUIRED)
+
+All commit messages MUST follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+### Format
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Commit Types and Version Impact
+- **feat**: New feature → minor version bump (0.5.0 → 0.6.0)
+- **fix**: Bug fix → patch version bump (0.5.0 → 0.5.1)
+- **perf**: Performance improvement → patch version bump
+- **docs**: Documentation only → no version bump
+- **style**: Formatting changes → no version bump
+- **refactor**: Code refactoring → no version bump
+- **test**: Test changes → no version bump
+- **build**: Build system changes → no version bump
+- **ci**: CI/CD changes → no version bump
+- **chore**: Other changes → no version bump
+
+### Breaking Changes
+For breaking changes (major version bump), add `!` after type or include `BREAKING CHANGE:` in footer:
+```
+feat(api)!: redesign authentication endpoints
+
+BREAKING CHANGE: OAuth2 tokens now required instead of API keys.
+```
+Result: 0.5.0 → 1.0.0
+
+### Scope Examples
+- `api` - REST API changes
+- `ui` - Frontend changes
+- `auth` - Authentication
+- `storage` - Storage providers
+- `ocr` - OCR processing
+- `tasks` - Celery tasks
+- `config` - Configuration
+- `docs` - Documentation
+
+### Commit Examples
+```
+feat(storage): add Amazon S3 storage provider
+fix(ocr): handle PDFs without text layer
+docs: update deployment guide with Docker setup
+refactor(tasks): consolidate duplicate code
+test: add integration tests for upload API
+chore: update dependencies for security fixes
+```
+
+## Semantic Release Process
+
+### Automated Versioning
+DocuElevate uses `python-semantic-release` for automated version management:
+
+1. **On merge to main**: semantic-release analyzes commit messages
+2. **Automatic actions**:
+   - Determines next version from commit types
+   - Updates `VERSION` file
+   - Generates/updates `CHANGELOG.md`
+   - Creates Git tag with `v` prefix (e.g., `v0.6.0`)
+   - Creates GitHub Release with auto-generated notes
+   - Triggers Docker image builds with version tag
+
+### Agent Rules for Versioning
+- ✅ **DO**: Write conventional commit messages
+- ✅ **DO**: Use appropriate commit types for your changes
+- ✅ **DO**: Mark breaking changes explicitly
+- ❌ **DON'T**: Manually edit `VERSION` file
+- ❌ **DON'T**: Manually edit `CHANGELOG.md`
+- ❌ **DON'T**: Create version tags or GitHub Releases manually
+
+These files are managed entirely by the semantic-release automation.

 ### File Organization
 - Place API endpoints in `app/api/` organized by feature
@@ -568,7 +568,7 @@ logger.info(f"Password: {password}")  # BAD!

 ---

-## 🔄 Git Workflow
+## 🔄 Git Workflow & Versioning

 ### Branch Names
 - `feature/description` - New features
@@ -577,28 +577,103 @@ logger.info(f"Password: {password}")  # BAD!
 - `refactor/description` - Code refactoring
 - `docs/description` - Documentation updates

-### Commit Messages
+### Conventional Commits (REQUIRED)
+
+**All commit messages MUST follow the Conventional Commits specification for automated versioning.**
+
+#### Format
 ```
-type(scope): Short description (max 72 chars)
+<type>(<scope>): <subject>

-Longer description if needed. Explain:
- What changed
- Why it changed
- Any breaking changes
+<body>

-Fixes #123
+<footer>
 ```

-Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+#### Commit Types and Version Bumps
+- **feat**: New feature → **minor version bump** (0.5.0 → 0.6.0)
+- **fix**: Bug fix → **patch version bump** (0.5.0 → 0.5.1)
+- **perf**: Performance improvement → **patch version bump**
+- **docs**: Documentation only → **no version bump**
+- **style**: Code style/formatting → **no version bump**
+- **refactor**: Code refactoring → **no version bump**
+- **test**: Test changes → **no version bump**
+- **build**: Build system changes → **no version bump**
+- **ci**: CI/CD changes → **no version bump**
+- **chore**: Other changes → **no version bump**
+
+#### Breaking Changes
+Add `!` after type/scope or include `BREAKING CHANGE:` in footer for **major version bump**:
+```
+feat(api)!: redesign authentication endpoints
+
+BREAKING CHANGE: OAuth2 tokens now required instead of API keys
+```
+Result: 0.5.0 → 1.0.0
+
+#### Scope Examples
+- `api` - REST API changes
+- `ui` - Frontend/UI changes
+- `auth` - Authentication
+- `storage` - Storage providers
+- `ocr` - OCR processing
+- `tasks` - Celery tasks
+- `config` - Configuration
+
+#### Good Commit Examples
+```
+feat(storage): add Amazon S3 storage provider
+
+Implements S3StorageProvider with upload, download, delete operations.
+Includes configuration for bucket, region, and credentials.
+
+Closes #123
+```
+
+```
+fix(ocr): handle PDFs without text layer
+
+Previously failed silently. Now properly processes through Azure.
+
+Fixes #456
+```
+
+```
+docs: update deployment guide with Docker Compose
+
+Added step-by-step instructions for Docker Compose deployment.
+```
+
+### Semantic Release Automation
+
+DocuElevate uses `python-semantic-release` for automated version management.
+
+#### How It Works
+1. **PR merges to main** with conventional commits
+2. **semantic-release analyzes** commit messages  
+3. **Automatic updates**:
+   - Bumps `VERSION` file
+   - Updates `CHANGELOG.md`
+   - Creates Git tag (e.g., `v0.6.0`)
+   - Creates GitHub Release
+   - Triggers Docker builds
+
+#### Agent Rules
+- ✅ **DO**: Write conventional commit messages
+- ✅ **DO**: Use correct commit types
+- ✅ **DO**: Include `BREAKING CHANGE:` when applicable
+- ❌ **DON'T**: Manually edit `VERSION` file
+- ❌ **DON'T**: Manually edit `CHANGELOG.md`
+- ❌ **DON'T**: Create version tags or releases manually

 ### Pull Requests
-1. Create PR with descriptive title
+1. Create PR with descriptive title (conventional format if single change)
 2. Fill out PR template
-3. Link related issues
+3. Link related issues  
 4. Ensure CI passes
 5. Request reviews
 6. Address feedback
-7. Squash merge when approved
+7. Merge when approved (commits retain conventional format)

 ---

@@ -607,6 +682,7 @@ Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
 Before submitting code:

 - [ ] Code follows style guide (Black formatted)
+- [ ] Commit messages use conventional commit format
 - [ ] All tests pass (`pytest`)
 - [ ] New code has tests
 - [ ] Coverage doesn't decrease
@@ -614,7 +690,7 @@ Before submitting code:
 - [ ] No secrets or credentials in code
 - [ ] Linting passes (`flake8`, `pylint`)
 - [ ] Type hints added (`mypy` clean)
- [ ] CHANGELOG.md updated (if user-facing)
+- [ ] No manual edits to `VERSION` or `CHANGELOG.md`
 - [ ] Security scan passed (`bandit`)

 Run full check:
@@ -31,8 +31,134 @@ We welcome feature requests! Please submit an issue with:
 1. Fork the repository
 2. Create a new branch for your changes
 3. Make your changes
-4. Run the tests to ensure everything works
-5. Submit a pull request with a clear description of the changes
+4. **Follow conventional commit format** (see below)
+5. Run the tests to ensure everything works
+6. Submit a pull request with a clear description of the changes
+
+## Commit Message Format
+
+DocuElevate follows the [Conventional Commits](https://www.conventionalcommits.org/) specification for commit messages. This enables automatic version bumping and changelog generation.
+
+### Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Type
+
+Must be one of the following:
+
+- **feat**: A new feature (triggers minor version bump)
+- **fix**: A bug fix (triggers patch version bump)
+- **docs**: Documentation only changes
+- **style**: Changes that don't affect code meaning (formatting, etc.)
+- **refactor**: Code change that neither fixes a bug nor adds a feature
+- **perf**: Performance improvement (triggers patch version bump)
+- **test**: Adding or updating tests
+- **build**: Changes to build system or dependencies
+- **ci**: Changes to CI configuration files and scripts
+- **chore**: Other changes that don't modify src or test files
+
+### Scope (Optional)
+
+The scope should be the name of the affected module or area:
+- `api` - REST API changes
+- `ui` - Frontend/UI changes
+- `auth` - Authentication changes
+- `storage` - Storage provider changes
+- `ocr` - OCR processing changes
+- `tasks` - Celery task changes
+- `config` - Configuration changes
+
+### Subject
+
+The subject contains a succinct description of the change:
+- Use imperative, present tense: "change" not "changed" nor "changes"
+- Don't capitalize first letter
+- No period (.) at the end
+
+### Breaking Changes
+
+For breaking changes, add `!` after the type/scope or include `BREAKING CHANGE:` in the footer:
+
+```
+feat!: redesign authentication API
+
+BREAKING CHANGE: The /api/auth endpoint now requires OAuth2 tokens instead of API keys.
+```
+
+This triggers a major version bump.
+
+### Examples
+
+```
+feat(storage): add support for Amazon S3 storage provider
+
+Add S3StorageProvider class with upload, download, and delete operations.
+Includes configuration options for bucket name, region, and credentials.
+
+Closes #123
+```
+
+```
+fix(ocr): handle PDF files without text layer
+
+Previously, PDFs without existing text layers would fail silently.
+Now properly processes them through Azure Document Intelligence.
+
+Fixes #456
+```
+
+```
+docs: update deployment guide with Docker Compose setup
+
+Added step-by-step instructions for deploying with Docker Compose,
+including environment variable configuration and service dependencies.
+```
+
+```
+chore: update dependencies to fix security vulnerabilities
+
+Updated authlib to 1.6.5+ and starlette to 0.49.1+
+```
+
+## Versioning and Releases
+
+DocuElevate uses [semantic-release](https://github.com/semantic-release/semantic-release) for automated version management and releases:
+
+- **Releases are automated**: When PRs are merged to `main`, semantic-release analyzes commit messages and automatically:
+  - Determines the next version number
+  - Updates the `VERSION` file
+  - Generates/updates `CHANGELOG.md`
+  - Creates a Git tag with `v` prefix (e.g., `v0.6.0`)
+  - Creates a GitHub Release with auto-generated notes
+  - Triggers Docker image builds with the new version tag
+
+- **Version Bumps**:
+  - `feat:` commits → minor version bump (0.5.0 → 0.6.0)
+  - `fix:` or `perf:` commits → patch version bump (0.5.0 → 0.5.1)
+  - `feat!:` or `BREAKING CHANGE:` → major version bump (0.5.0 → 1.0.0)
+  - Other commit types (docs, chore, etc.) → no version bump
+
+- **Manual Version Changes**: Do NOT manually edit `VERSION` or `CHANGELOG.md` - these are managed by semantic-release
+
+## Pull Request Checklist
+
+Before submitting a pull request:
+
+- [ ] Code follows the project style guide (Black, isort, flake8)
+- [ ] Commit messages follow conventional commit format
+- [ ] Tests added/updated for new functionality
+- [ ] Documentation updated if user-facing changes
+- [ ] No manual edits to `VERSION` or `CHANGELOG.md`
+- [ ] All tests pass locally
+- [ ] Pre-commit hooks pass
+- [ ] Security scan passes (if applicable)

 ## Development Environment

@@ -40,8 +166,8 @@ We welcome feature requests! Please submit an issue with:

 ```bash
 # Clone the repository
-git clone https://github.com/christianlouis/document-processor.git
-cd document-processor
+git clone https://github.com/christianlouis/DocuElevate.git
+cd DocuElevate

 # Create a virtual environment
 python -m venv venv