Merge pull request #135 from christianlouis/copilot/implement-semantic-release

feat: implement semantic-release and conventional commits for automated versioning
2026-02-08 09:05:19 +01:00
parent 54414c53fe 67cbc5e80d
commit 93149d0c56
18 changed files with 720 additions and 36 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
@@ -17,7 +17,7 @@ on:
      - main

 env:
-  IMAGE_NAME: christianlouis/document-processor
+  IMAGE_NAME: christianlouis/docuelevate

 jobs:
  docker:
@@ -58,7 +58,7 @@ jobs:
        with:
          images: |
            ${{ env.IMAGE_NAME }}
-            ghcr.io/${{ github.repository_owner }}/document-processor
+            ghcr.io/${{ github.repository_owner }}/docuelevate

      - name: Build and Push Docker Image with Provenance and SBOM
        uses: docker/build-push-action@v6
@@ -72,9 +72,9 @@ jobs:
          tags: |
            ${{ env.IMAGE_NAME }}:latest
            ${{ env.IMAGE_NAME }}:${{ github.sha }}
-            ghcr.io/${{ github.repository_owner }}/document-processor:latest
-            ghcr.io/${{ github.repository_owner }}/document-processor:${{ github.sha }}
+            ghcr.io/${{ github.repository_owner }}/docuelevate:latest
+            ghcr.io/${{ github.repository_owner }}/docuelevate:${{ github.sha }}
            ${{ startsWith(github.ref, 'refs/tags/') && format('{0}:{1}', env.IMAGE_NAME, env.VERSION) || '' }}
-            ${{ startsWith(github.ref, 'refs/tags/') && format('ghcr.io/{0}/document-processor:{1}', github.repository_owner, env.VERSION) || '' }}
+            ${{ startsWith(github.ref, 'refs/tags/') && format('ghcr.io/{0}/docuelevate:{1}', github.repository_owner, env.VERSION) || '' }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
@@ -0,0 +1,71 @@
+name: Semantic Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  packages: write
+
+jobs:
+  release:
+    name: Semantic Release
+    runs-on: ubuntu-latest
+    if: github.repository == 'christianlouis/DocuElevate'
+    
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install python-semantic-release
+      
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+      
+      - name: Run Semantic Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          semantic-release version --print
+          semantic-release version
+          semantic-release publish
+      
+      - name: Update VERSION file if changed
+        run: |
+          if [ -f VERSION ]; then
+            git add VERSION
+            if ! git diff --staged --quiet; then
+              git commit -m "chore(release): update VERSION file [skip ci]"
+              git push
+            fi
+          fi
+      
+      - name: Trigger Docker Build on Tag
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const ref = context.ref;
+            const tag = ref.replace('refs/tags/', '');
+            console.log(`New tag created: ${tag}`);
+            console.log('Docker build will be triggered automatically by the docker-build workflow');
@@ -69,3 +69,11 @@ repos:
            .+\.json|
            .env.demo
          )$
+
+  # Conventional commits validation
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v3.0.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args: []
@@ -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:
@@ -5,8 +5,39 @@ All notable changes to DocuElevate will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## Important Note
+
+**As of v0.6.0**: This CHANGELOG is automatically generated and maintained by [python-semantic-release](https://github.com/python-semantic-release/python-semantic-release). Do not edit manually.
+
+**Prior to v0.6.0**: This CHANGELOG was manually maintained. The transition to automated releases includes:
+- Standardized tag format with `v` prefix (e.g., `v0.6.0`)
+- Automated version bumping based on conventional commits
+- Auto-generated release notes from commit messages
+
+---
+
 ## [Unreleased]

+### Added
+- Automated semantic versioning with python-semantic-release
+- Conventional commit validation via commitlint
+- Automated CHANGELOG generation
+- Automated GitHub Release creation with notes
+- Documentation archive for one-off documents
+
+### Changed
+- Docker image name from `christianlouis/document-processor` to `christianlouis/docuelevate`
+- GHCR image references updated to `docuelevate`
+- Comprehensive documentation updates for versioning and release process
+
+### Documentation
+- Added conventional commits guide to CONTRIBUTING.md
+- Updated AGENTIC_CODING.md with versioning/release process
+- Updated .github/copilot-instructions.md with commit format rules
+- Archived historical one-off documentation to docs/archive/
+
+---
+
 ## [0.5.0] - 2026-02-08

 ### Added
@@ -167,11 +198,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ---

-[Unreleased]: https://github.com/christianlouis/DocuElevate/compare/v0.5.0...HEAD
-[0.5.0]: https://github.com/christianlouis/DocuElevate/compare/v0.3.3...v0.5.0
-[0.3.3]: https://github.com/christianlouis/DocuElevate/compare/v0.3.2...v0.3.3
-[0.3.2]: https://github.com/christianlouis/DocuElevate/compare/v0.3.1...v0.3.2
-[0.3.1]: https://github.com/christianlouis/DocuElevate/compare/v0.3.0...v0.3.1
-[0.3.0]: https://github.com/christianlouis/DocuElevate/compare/v0.2.0...v0.3.0
-[0.2.0]: https://github.com/christianlouis/DocuElevate/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/christianlouis/DocuElevate/releases/tag/v0.1.0
+## Historical Release Links
+
+**Note**: Tags v0.3.1, v0.3.2, v0.3.3, and v0.5.0 do not exist as GitHub Releases. The features described in those versions were included in the codebase but not formally released. The latest actual release is 0.4.3. Going forward (v0.6.0+), all releases will have corresponding GitHub Releases and tags created automatically by semantic-release.
+
+[Unreleased]: https://github.com/christianlouis/DocuElevate/compare/0.4.3...HEAD
+[0.3.0]: https://github.com/christianlouis/DocuElevate/compare/0.2...0.3
+[0.2.0]: https://github.com/christianlouis/DocuElevate/compare/0.1...0.2
+[0.1.0]: https://github.com/christianlouis/DocuElevate/releases/tag/0.1
@@ -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
@@ -27,9 +27,18 @@ DocuElevate follows [Semantic Versioning 2.0.0](https://semver.org/):
 - **Database-backed settings management with encryption**
 - **Setup wizard for first-time configuration**
 - **Admin UI for runtime configuration**
+- **Automated semantic versioning and releases**
 - OAuth2 authentication with admin group support
 - Basic web UI and REST API

+### Important Note on Versioning
+As of February 2026, DocuElevate uses **automated semantic versioning**:
+- Version management handled by `python-semantic-release`
+- Releases automated via GitHub Actions on merge to main
+- Version bumps determined by conventional commit messages
+- `VERSION` and `CHANGELOG.md` automatically updated
+- GitHub Releases created automatically with release notes
+
 ---

 ## Previous Releases
@@ -237,7 +246,27 @@ This is our first major release, marking production-ready enterprise capabilitie

 ## Release Process

-### Pre-release Checklist
+### Automated Semantic Versioning (v0.6.0+)
+Starting with v0.6.0, releases are fully automated using `python-semantic-release`:
+
+1. **Commit with Conventional Format**: Use conventional commit messages (feat, fix, etc.)
+2. **Merge to Main**: PR merges trigger semantic-release workflow
+3. **Automated Analysis**: semantic-release determines version from commits
+4. **Automatic Updates**:
+   - Updates `VERSION` file
+   - Generates/updates `CHANGELOG.md`
+   - Creates Git tag (e.g., `v0.6.0`)
+   - Creates GitHub Release with notes
+   - Triggers Docker image builds
+5. **No Manual Steps**: VERSION and CHANGELOG are never edited manually
+
+### Version Bump Rules
+- `feat:` commits → Minor version (0.5.0 → 0.6.0)
+- `fix:`, `perf:` → Patch version (0.5.0 → 0.5.1)
+- `feat!:`, `BREAKING CHANGE:` → Major version (0.5.0 → 1.0.0)
+- Other types (docs, chore, etc.) → No version bump
+
+### Pre-release Checklist (Automated)
 - [ ] All tests passing
 - [ ] Security scan passed
 - [ ] Code review completed
@@ -46,6 +46,12 @@ DocuElevate aims to be the premier open-source intelligent document processing p
  - [ ] Implement API key rotation
  - [ ] Add audit logging for sensitive operations

+- **Release Automation** (Completed ✅)
+  - [x] Implement semantic-release for automated versioning
+  - [x] Add conventional commit validation
+  - [x] Automate CHANGELOG generation
+  - [x] Integrate Docker builds with releases
+
 ### Features - v0.4.0
 - **Enhanced Search & Filtering**
  - [ ] Full-text search across documents
@@ -7,6 +7,15 @@ This document tracks actionable tasks for the current development cycle. For lon

 ---

+## ⚠️ Important Note on Versioning
+
+As of this update, DocuElevate uses **automated semantic versioning** via `python-semantic-release`:
+- **DO NOT** manually edit `VERSION` or `CHANGELOG.md` 
+- Version bumps are automated based on conventional commit messages
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for commit message format
+
+---
+
 ## 🔴 Critical Priority (This Week)

 ### Security
@@ -46,6 +55,8 @@ This document tracks actionable tasks for the current development cycle. For lon
 - [x] Enable tests in GitHub Actions
 - [x] Add coverage reporting
 - [x] Add CodeQL scanning
+- [x] Implement semantic-release for automated versioning
+- [x] Add conventional commit validation (commitlint)
 - [ ] Add dependency scanning (Dependabot or similar)
 - [ ] Make linting checks blocking (once critical issues fixed)
 - [ ] Add build status badges to README.md
@@ -55,8 +66,9 @@ This document tracks actionable tasks for the current development cycle. For lon
 - [x] Create MILESTONES.md
 - [x] Create TODO.md
 - [x] Create SECURITY_AUDIT.md
- [ ] Create AGENTIC_CODING.md
- [ ] Update CONTRIBUTING.md with testing guidelines
+- [x] Create AGENTIC_CODING.md
+- [x] Update CONTRIBUTING.md with testing guidelines and conventional commits
+- [x] Archive one-off documentation files to docs/archive/
 - [ ] Add architecture diagram to docs/
 - [ ] Document all environment variables in docs/ConfigurationGuide.md
 - [ ] Add troubleshooting section for common test failures
@@ -214,7 +226,18 @@ This document tracks actionable tasks for the current development cycle. For lon

 ## ✅ Completed (Recent)

-### 2026-02-08
+### 2026-02-08 (Semantic Release & Documentation Overhaul)
+- [x] Implemented semantic-release with python-semantic-release
+- [x] Created pyproject.toml with semantic-release configuration
+- [x] Added .github/workflows/release.yml for automated releases
+- [x] Added conventional commit validation (commitlint) to pre-commit hooks
+- [x] Updated Docker workflow to use docuelevate image name
+- [x] Archived one-off documentation to docs/archive/
+- [x] Updated CONTRIBUTING.md with conventional commits guide
+- [x] Updated AGENTIC_CODING.md with versioning/release process
+- [x] Updated .github/copilot-instructions.md with commit format rules
+
+### 2026-02-08 (Settings Management)
 - [x] Implemented database-backed settings management system
 - [x] Added Fernet encryption for sensitive settings in database
 - [x] Created 3-step setup wizard for fresh installations
@@ -0,0 +1,33 @@
+# Documentation Archive
+
+This directory contains historical documentation that was created for specific one-time tasks or analysis. These documents are preserved for reference but are not part of the ongoing documentation set.
+
+## Archived Documents
+
+### Analysis & Research
+- **`ANALYSIS_SUMMARY.md`** - One-off analysis document from a specific feature investigation
+- **`FRAMEWORK_ANALYSIS.md`** - Framework decision rationale and comparison document
+- **`SETTINGS_IMPLEMENTATION.md`** - Implementation notes for the settings management feature
+
+### Task-Specific Documents
+- **`IMPLEMENTATION_CHECKLIST.md`** - Task-specific checklist for a completed feature
+- **`FILENAME_FIX_SUMMARY.md`** - Summary of filename-related fixes
+
+## Why Archive?
+
+These documents provided value during specific development phases but:
+- Are not part of ongoing user or developer documentation
+- Document completed one-time tasks
+- Contain information that has been integrated into other docs
+- Were created for specific decision-making processes
+
+## Active Documentation
+
+For current, maintained documentation, see:
+- **Root Level**: `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `ROADMAP.md`
+- **`docs/`**: User guides, API docs, deployment guides, configuration references
+- **`AGENTIC_CODING.md`**: Developer and AI agent guidelines
+
+---
+
+*Last Updated: 2026-02-08*
@@ -0,0 +1,200 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "docuelevate"
+dynamic = ["version"]
+description = "Intelligent document processing system with AI-powered metadata extraction"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "Apache-2.0"}
+authors = [
+    {name = "Christian Louis", email = "christianlouis@users.noreply.github.com"}
+]
+keywords = ["document", "processing", "ocr", "ai", "metadata", "extraction"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/christianlouis/DocuElevate"
+Documentation = "https://github.com/christianlouis/DocuElevate/tree/main/docs"
+Repository = "https://github.com/christianlouis/DocuElevate"
+Issues = "https://github.com/christianlouis/DocuElevate/issues"
+Changelog = "https://github.com/christianlouis/DocuElevate/blob/main/CHANGELOG.md"
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.semantic_release]
+version_toml = []
+version_source = "tag"
+commit_version_number = true
+tag_format = "v{version}"
+major_on_zero = false
+allow_zero_version = true
+build_command = """
+    chmod +x scripts/generate_build_metadata.sh
+    ./scripts/generate_build_metadata.sh
+"""
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+[tool.semantic_release.changelog]
+template_dir = "templates"
+exclude_commit_patterns = [
+    "^chore\\(release\\):",
+    "^Merge",
+    "^Bump version",
+]
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"
+
+[tool.semantic_release.changelog.environment]
+block_start_string = "{%"
+block_end_string = "%}"
+variable_start_string = "{{"
+variable_end_string = "}}"
+comment_start_string = "{#"
+comment_end_string = "#}"
+trim_blocks = false
+lstrip_blocks = false
+newline_sequence = "\n"
+keep_trailing_newline = false
+extensions = []
+autoescape = true
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = [
+    "feat",
+    "fix",
+    "docs",
+    "style",
+    "refactor",
+    "perf",
+    "test",
+    "build",
+    "ci",
+    "chore",
+]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+default_bump_level = 0
+
+[tool.semantic_release.remote]
+name = "origin"
+type = "github"
+ignore_token_for_push = false
+
+[tool.semantic_release.remote.token]
+env = "GH_TOKEN"
+
+[tool.semantic_release.publish]
+dist_glob_patterns = []
+upload_to_vcs_release = true
+upload_to_pypi = false
+upload_to_repository = false
+
+# Black configuration
+[tool.black]
+line-length = 120
+target-version = ['py311']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+  | migrations
+)/
+'''
+
+# isort configuration
+[tool.isort]
+profile = "black"
+line_length = 120
+skip_gitignore = true
+known_first_party = ["app"]
+sections = ["FUTURE", "STDLIB", "THIRDPARTY", "FIRSTPARTY", "LOCALFOLDER"]
+
+# pytest configuration
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--strict-markers",
+    "--strict-config",
+    "--cov=app",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+    "--cov-branch",
+]
+markers = [
+    "unit: Unit tests for individual functions/methods",
+    "integration: Integration tests for API endpoints and workflows",
+    "slow: Tests that take significant time to run",
+    "security: Security-related tests",
+    "requires_external: Tests requiring external services (OpenAI, Azure, etc.)",
+    "requires_db: Tests requiring database",
+    "requires_redis: Tests requiring Redis",
+]
+
+# mypy configuration
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+ignore_missing_imports = true
+
+# Coverage configuration
+[tool.coverage.run]
+source = ["app"]
+omit = [
+    "*/tests/*",
+    "*/migrations/*",
+    "*/__pycache__/*",
+    "*/venv/*",
+    "*/env/*",
+]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]
@@ -23,4 +23,7 @@ safety>=3.0.0
 pre-commit>=3.6.0

 # License compliance
-pip-licenses==5.5.1  # For license compliance checking
+pip-licenses==5.5.1  # For license compliance checking
+
+# Release automation
+python-semantic-release>=9.0.0