gitea-admin/gh-christianlouis-docuelevate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add comprehensive conventional commits and semantic-release guide

Browse Source 
- 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>
This commit is contained in:
copilot-swe-agent[bot]
2026-02-08 07:55:03 +00:00
parent 6437f01434
commit d2d4f113d0
3 changed files with 298 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/copilot-instructions.md
+79 -1
View File
@@ -105,10 +105,88 @@ DocuElevate is an intelligent document processing system that automates handling
### Git Workflow ### Git Workflow
- Write clear, descriptive commit messages - Write clear, descriptive commit messages
- **ALWAYS follow Conventional Commits format** (see below)
- Keep commits focused and atomic - Keep commits focused and atomic
- Run tests and linters before committing - Run tests and linters before committing
- Pre-commit hooks are configured (`.pre-commit-config.yaml`) - 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 ### File Organization
- Place API endpoints in `app/api/` organized by feature - Place API endpoints in `app/api/` organized by feature
AGENTIC_CODING.md
+88 -12
View File
@@ -568,7 +568,7 @@ logger.info(f"Password: {password}") # BAD!
--- ---
## 🔄 Git Workflow ## 🔄 Git Workflow & Versioning
### Branch Names ### Branch Names
- `feature/description` - New features - `feature/description` - New features
@@ -577,28 +577,103 @@ logger.info(f"Password: {password}") # BAD!
- `refactor/description` - Code refactoring - `refactor/description` - Code refactoring
- `docs/description` - Documentation updates - `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: <body>
- What changed
- Why it changed
- Any breaking changes
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 ### Pull Requests
1. Create PR with descriptive title 1. Create PR with descriptive title (conventional format if single change)
2. Fill out PR template 2. Fill out PR template
3. Link related issues 3. Link related issues
4. Ensure CI passes 4. Ensure CI passes
5. Request reviews 5. Request reviews
6. Address feedback 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: Before submitting code:
- [ ] Code follows style guide (Black formatted) - [ ] Code follows style guide (Black formatted)
- [ ] Commit messages use conventional commit format
- [ ] All tests pass (`pytest`) - [ ] All tests pass (`pytest`)
- [ ] New code has tests - [ ] New code has tests
- [ ] Coverage doesn't decrease - [ ] Coverage doesn't decrease
@@ -614,7 +690,7 @@ Before submitting code:
- [ ] No secrets or credentials in code - [ ] No secrets or credentials in code
- [ ] Linting passes (`flake8`, `pylint`) - [ ] Linting passes (`flake8`, `pylint`)
- [ ] Type hints added (`mypy` clean) - [ ] Type hints added (`mypy` clean)
- [ ] CHANGELOG.md updated (if user-facing) - [ ] No manual edits to `VERSION` or `CHANGELOG.md`
- [ ] Security scan passed (`bandit`) - [ ] Security scan passed (`bandit`)
Run full check: Run full check:
CONTRIBUTING.md
+130 -4
View File
@@ -31,8 +31,134 @@ We welcome feature requests! Please submit an issue with:
1. Fork the repository 1. Fork the repository
2. Create a new branch for your changes 2. Create a new branch for your changes
3. Make your changes 3. Make your changes
4. Run the tests to ensure everything works 4. **Follow conventional commit format** (see below)
5. Submit a pull request with a clear description of the changes 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 ## Development Environment
@@ -40,8 +166,8 @@ We welcome feature requests! Please submit an issue with:
```bash ```bash
# Clone the repository # Clone the repository
git clone https://github.com/christianlouis/document-processor.git git clone https://github.com/christianlouis/DocuElevate.git
cd document-processor cd DocuElevate
# Create a virtual environment # Create a virtual environment
python -m venv venv python -m venv venv