Merge pull request #481 from nanotaboada/docs/release-workflow-standardization

docs: standardize release workflow and improve documentation quality

Author: nanotaboada

AGENTS.md

@@ -92,9 +92,11 @@ black .
 
 **Pre-commit checklist**:
 
-1. Run `flake8 .` - must pass with no errors
-2. Run `black --check .` - must pass with no formatting changes needed (or run `black .` to auto-fix)
-3. Run `pytest --cov=./ --cov-report=term` - all tests must pass
+1. Update CHANGELOG.md `[Unreleased]` section with your changes (Added/Changed/Deprecated/Removed/Fixed/Security)
+2. Run `flake8 .` - must pass with no errors
+3. Run `black --check .` - must pass with no formatting changes needed (or run `black .` to auto-fix)
+4. Run `pytest --cov=./ --cov-report=term` - all tests must pass
+5. Follow conventional commit format (enforced by commitlint)
 
 **Style rules** (enforced by Black + Flake8):
 
@@ -147,6 +149,71 @@ curl http://localhost:9000/health
 
 **First run behavior**: Container copies pre-seeded SQLite database into persistent volume. Subsequent runs reuse that volume to preserve data.
 
+## Release Management
+
+### CHANGELOG Maintenance
+
+**Important**: Update CHANGELOG.md continuously as you work, not just before releases.
+
+**For every meaningful commit**:
+
+1. Add your changes to the `[Unreleased]` section in CHANGELOG.md
+2. Categorize under the appropriate heading:
+   - **Added**: New features
+   - **Changed**: Changes in existing functionality
+   - **Deprecated**: Soon-to-be removed features
+   - **Removed**: Removed features
+   - **Fixed**: Bug fixes
+   - **Security**: Security vulnerability fixes
+3. Use clear, user-facing descriptions (not just commit messages)
+4. Include PR/issue numbers when relevant (#123)
+
+**Example**:
+
+```markdown
+## [Unreleased]
+
+### Added
+- User authentication with JWT tokens (#145)
+- Rate limiting middleware for API endpoints
+
+### Deprecated
+- Legacy authentication endpoint /api/v1/auth (use /api/v2/auth instead)
+
+### Fixed
+- Null reference exception in player service (#147)
+
+### Security
+- Fix SQL injection vulnerability in search endpoint (#148)
+```
+
+### Creating a Release
+
+When ready to release:
+
+1. **Update CHANGELOG.md**: Move items from `[Unreleased]` to a new versioned section, then commit and push:
+
+   ```markdown
+   ## [1.1.0 - bielsa] - 2026-02-15
+   ```
+
+   ```bash
+   git add CHANGELOG.md
+   git commit -m "docs: prepare changelog for v1.1.0-bielsa release"
+   git push
+   ```
+
+2. **Create and push tag**:
+
+   ```bash
+   git tag -a v1.1.0-bielsa -m "Release 1.1.0 - Bielsa"
+   git push origin v1.1.0-bielsa
+   ```
+
+3. **CD workflow runs automatically** to publish Docker images and create GitHub Release
+
+See [CHANGELOG.md](CHANGELOG.md#how-to-release) for complete release instructions and coach naming convention.
+
 ## CI/CD Pipeline
 
 ### Continuous Integration (python-ci.yml)
@@ -157,7 +224,7 @@ curl http://localhost:9000/health
 
 1. **Lint**: Commit messages (commitlint) → Flake8 → Black check
 2. **Test**: pytest with verbose output → coverage report generation
-3. **Coverage**: Upload to Codecov and Codacy (requires secrets)
+3. **Coverage**: Upload to Codecov (requires secrets)
 
 **Local validation** (run this before pushing):
 
@@ -387,6 +454,7 @@ Settings (`.vscode/settings.json`):
 
 ## Important Notes
 
+- **CHANGELOG maintenance**: Update CHANGELOG.md `[Unreleased]` section with every meaningful change
 - **Never commit secrets**: No API keys, tokens, or credentials in code
 - **Test coverage**: Maintain existing coverage levels (currently high)
 - **Commit messages**: Follow conventional commits (enforced by commitlint)

CHANGELOG.md

@@ -46,64 +46,88 @@ This project uses famous football coaches as release codenames, following an A-Z
 
 ### Changed
 
-### Fixed
+### Deprecated
 
 ### Removed
 
----
+### Fixed
 
-## [1.0.0 - Ancelotti] - TBD
+### Security
 
-### Added
+---
 
-- Initial stable release
-- Player CRUD operations with FastAPI
-- SQLite database with SQLAlchemy (async)
-- Docker support with Docker Compose
-- In-memory caching with aiocache (10 min TTL)
-- Comprehensive pytest test suite with coverage reporting
-- Health check endpoint
-- CI/CD pipeline with tag-based releases
-- Famous coaches release naming convention ♟️
+## [1.0.0 - Ancelotti] - 2026-01-24
 
-### Changed
+Initial release. See [README.md](README.md) for complete feature list and documentation.
 
-- N/A
+---
 
-### Fixed
+## How to Release
 
-- N/A
+To create a new release, follow these steps in order:
 
-### Removed
+### 1. Update CHANGELOG.md
 
-- N/A
+Move items from the `[Unreleased]` section to a new release section using the template format provided at the bottom of this file (see the commented template).
 
----
+**Important:** Commit and push this change before creating the tag.
 
-## How to Release
+### 2. Create and Push Version Tag
 
-1. Update this CHANGELOG.md with the new version details
-2. Create a tag with the format `v{MAJOR}.{MINOR}.{PATCH}-{COACH}`
-3. Push the tag to trigger the CD pipeline
+```bash
+git tag -a vX.Y.Z-coach -m "Release X.Y.Z - Coach"
+git push origin vX.Y.Z-coach
+```
+
+Example:
 
 ```bash
-# Example: Creating the first release (Ancelotti)
 git tag -a v1.0.0-ancelotti -m "Release 1.0.0 - Ancelotti"
 git push origin v1.0.0-ancelotti
 ```
 
-The CD pipeline will automatically:
+### 3. Automated CD Workflow
+
+The CD workflow automatically:
 
-- Run tests and generate coverage reports
-- Build and push Docker images with multiple tags (`:1.0.0`, `:ancelotti`, `:latest`)
-- Generate a changelog from git commits
-- Create a GitHub Release with auto-generated notes
+- ✅ Validates the coach name against the A-Z list
+- ✅ Builds and tests the project with coverage
+- ✅ Publishes Docker images to GHCR with three tags (`:X.Y.Z`, `:coach`, `:latest`)
+- ✅ Creates a GitHub Release with auto-generated notes from commits
 
-## Version History
+### Pre-Release Checklist
 
-<!--
-Add release summaries here as they are published:
+- [ ] CHANGELOG.md updated with release notes
+- [ ] CHANGELOG.md changes committed and pushed
+- [ ] Tag created with correct format: `vX.Y.Z-coach`
+- [ ] Coach name is valid (A-Z from table above)
+- [ ] Tag pushed to trigger CD workflow
+
+<!-- Template for new releases:
+
+## [X.Y.Z - COACH_NAME] - YYYY-MM-DD
+
+### Added
+- New features
+
+### Changed
+- Changes in existing functionality
+
+### Deprecated
+- Soon-to-be removed features
+
+### Removed
+- Removed features
+
+### Fixed
+- Bug fixes
+
+### Security
+- Security vulnerability fixes
 
-### [1.0.0 - Ancelotti] (2026-XX-XX)
-- Initial stable release with core functionality
 -->
+
+---
+
+[unreleased]: https://github.com/nanotaboada/python-samples-fastapi-restful/compare/v1.0.0-ancelotti...HEAD
+[1.0.0 - Ancelotti]: https://github.com/nanotaboada/python-samples-fastapi-restful/releases/tag/v1.0.0-ancelotti

README.md

@@ -13,6 +13,17 @@
 
 Proof of Concept for a RESTful API made with [Python 3](https://www.python.org/) and [FastAPI](https://fastapi.tiangolo.com/).
 
+## Features
+
+- 🏗️ **Modern async architecture** - Async/await throughout, Pydantic validation, and SQLAlchemy 2.0+ patterns
+- 📚 **Interactive API exploration** - Auto-generated OpenAPI docs with FastAPI's built-in Swagger UI
+- ⚡ **Performance optimizations** - Async SQLAlchemy, in-memory caching with aiocache, and efficient database operations
+- 🧪 **High test coverage** - Pytest suite with 80% minimum coverage and automated reporting to Codecov
+- 📖 **Token-efficient documentation** - AGENTS.md + auto-loaded Copilot instructions for AI-assisted development
+- 🐳 **Full containerization** - Production-ready Docker setup with Docker Compose orchestration
+- 🔄 **Complete CI/CD pipeline** - Automated linting (Black/Flake8), testing, Docker publishing, and GitHub releases
+- ♟️ **Coach-themed semantic versioning** - Memorable, alphabetical release names honoring legendary football coaches
+
 ## Structure
 
 ![Simplified, conceptual project structure and main application flow](assets/images/structure.svg)
@@ -88,20 +99,39 @@ This project uses famous football coaches as release names ♟️
 
 ### Create a Release
 
-Releases are created by pushing version tags in the format `v{MAJOR}.{MINOR}.{PATCH}-{COACH}`:
+To create a new release, follow this workflow:
+
+#### 1. Update CHANGELOG.md
+
+First, document your changes in [CHANGELOG.md](CHANGELOG.md):
+
+```bash
+# Move items from [Unreleased] to new release section
+# Example: [1.0.0 - Ancelotti] - 2026-02-15
+git add CHANGELOG.md
+git commit -m "docs: prepare changelog for v1.0.0-ancelotti release"
+git push
+```
+
+#### 2. Create and Push Tag
+
+Then create and push the version tag:
 
 ```bash
-# Example: Creating the first release (Ancelotti)
 git tag -a v1.0.0-ancelotti -m "Release 1.0.0 - Ancelotti"
 git push origin v1.0.0-ancelotti
 ```
 
-The CD pipeline will automatically:
+#### 3. Automated CD Workflow
+
+This triggers the CD workflow which automatically:
+
+1. Validates the coach name
+2. Builds and tests the project with coverage
+3. Publishes Docker images to GitHub Container Registry with three tags
+4. Creates a GitHub Release with auto-generated changelog from commits
 
-- Run tests and generate coverage reports
-- Build and push Docker images with multiple tags
-- Generate a changelog from git commits
-- Create a GitHub Release with auto-generated notes
+> 💡 Always update CHANGELOG.md before creating the tag. See [CHANGELOG.md](CHANGELOG.md#how-to-release) for detailed release instructions.
 
 ### Pull Docker Images
 
@@ -118,7 +148,7 @@ docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:ancelotti
 docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:latest
 ```
 
-> 💡 **Note:** See [CHANGELOG.md](CHANGELOG.md) for the complete coach list (A-Z) and release history.
+> 💡 See [CHANGELOG.md](CHANGELOG.md) for the complete coach list (A-Z) and release history.
 
 ## Credits