diff --git a/AGENTS.md b/AGENTS.md index 9d03807..c75154f 100644 --- a/AGENTS.md +++ b/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) diff --git a/CHANGELOG.md b/CHANGELOG.md index c8eff6f..8491ef5 100644 --- a/CHANGELOG.md +++ b/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 - + +--- + +[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 diff --git a/README.md b/README.md index 7d50c62..12a27bb 100644 --- a/README.md +++ b/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