-
Notifications
You must be signed in to change notification settings - Fork 0
Release Process
This document describes the automated release process for tail-lookup.
Releases are automatically created when code is merged from develop to main. The process is fully automated and includes:
- Semantic versioning (MAJOR.MINOR.PATCH)
- Automatic version bump detection
- GitHub release creation with release notes
- Docker image tagging with version number
- Database artifact upload (aircraft.db)
- Database statistics in release notes
develop (active development)
↓
PR → main (production releases)
↓
Automatic release created with database
The release workflow automatically determines the version bump type based on commit messages:
Triggered by commit messages containing:
breaking:major:
Example: breaking: Change API endpoint structure
Triggered by commit messages containing:
feat:feature:minor:
Example: feat: Add caching layer for frequent lookups
All other commits (bug fixes, documentation, etc.)
Example: fix: Correct NO-ENG and NO-SEATS parsing
# Work on develop branch
git checkout develop
git pull origin develop
# Make changes
git add .
git commit -m "feat: Add new API endpoint"
git push origin develop# Create PR from develop to main
gh pr create --base main --head develop \
--title "Release: [Brief description]" \
--body "$(cat <<'EOF'
## Summary
[Describe changes]
## Changes
- Feature 1
- Feature 2
- Bug fix 1
## Database Changes
- Updated FAA data parsing
- Added new fields: [list]
## Testing
- [ ] Local testing complete
- [ ] Docker build successful
- [ ] API tests passed
- [ ] Database integrity verified
## Docker Images
- ryakel/tail-lookup:latest
EOF
)"When the PR is merged to main:
The Main Branch Build Workflow (build-main.yml) runs and performs the following:
-
Version Determination:
- Analyzes commits since last tag
- Determines version bump (major/minor/patch) based on commit messages
- Creates new semantic version tag
-
Database Preparation:
- Builds database from FAA data or downloads from latest release
-
Docker Build and Publish:
- Builds multi-architecture images (amd64, arm64) in parallel
- Pushes to Docker Hub with digest
- Creates multi-platform manifest
- Tags with
latest, date stamp, and version number
-
Release Creation:
- Analyzes commits since last release
- Determines version bump (major/minor/patch)
- Builds fresh database for statistics
- Creates Git tag (e.g.,
v1.2.3) - Extracts recent changes from changelog
- Creates GitHub Release with:
- Release notes
- Database statistics (record count, update date)
- Database artifact (aircraft.db)
- Docker pull commands
- Integration instructions
The release includes:
-
Version tag (e.g.,
v1.2.3) -
Release notes with:
- Database information (records, last updated)
- Quick start instructions
- Integration guide for consuming applications
- Recent changes
- Docker pull commands
- Full commit list
-
Docker images automatically tagged:
ryakel/tail-lookup:latestryakel/tail-lookup:YYYY-MM-DD
-
Database artifact (
aircraft.db) attached to release
Each release includes the FAA database as a downloadable artifact:
# Download database from latest release
curl -L -o aircraft.db \
https://github.com/ryakel/tail-lookup/releases/latest/download/aircraft.db
# Or use in your own application
wget https://github.com/ryakel/tail-lookup/releases/latest/download/aircraft.dbThe database is automatically:
- Built from latest FAA data
- Statistics calculated (record count)
- Uploaded as release asset
- Used by subsequent builds (downloaded instead of rebuilt)
Use semantic commit messages for proper version bumping:
# Major version bump (breaking changes)
git commit -m "breaking: Change API response structure"
# Minor version bump (new features)
git commit -m "feat: Add aircraft manufacturer search endpoint"
git commit -m "feature: Implement caching layer"
# Patch version bump (bug fixes, docs, etc)
git commit -m "fix: Correct NO-ENG parsing from MASTER.txt"
git commit -m "docs: Update API documentation"
git commit -m "chore: Update dependencies"Keep the wiki's Changelog.md up to date with all changes. The release workflow uses this for generating release notes.
Document changes in the Changelog under the "Latest Changes" section with clear descriptions:
### Feature Name (YYYY-MM-DD)
- **Key change**: Description of change
- **Impact**: How it affects users/system
- **Benefits**: What improvements this provides
### Bug Fix Name (YYYY-MM-DD)
- **Fixed**: Description of what was broken
- **Root cause**: Why it happened
- **Solution**: How it was resolved
- **Result**: Improved behaviorAfter a release is created, Docker images are automatically available:
# Pull specific date version
docker pull ryakel/tail-lookup:2025-11-28
# Pull latest
docker pull ryakel/tail-lookup:latest
# Run the service
docker run -d -p 8080:8080 ryakel/tail-lookup:latest
# Test the API
curl http://localhost:8080/api/v1/aircraft/N172SPAfter tail-lookup releases, consuming applications can update their deployment configurations:
# docker-compose.yml example
services:
tail-lookup:
image: ryakel/tail-lookup:latest # or specific version
# ... rest of configDownstream application workflows can automatically download the latest database from tail-lookup releases for custom builds or validation.
In addition to releases, nightly builds run automatically:
- Schedule: Every night at 2 AM UTC
- Purpose: Keep FAA data fresh
-
Process:
- Build fresh database from FAA data
- Build multi-arch images in parallel
- Push to Docker Hub with date tag
- No GitHub release created
# Pull nightly build
docker pull ryakel/tail-lookup:2025-11-28If you need to create a manual release:
# Create and push tag
git checkout main
git pull origin main
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3
# Build database manually
python scripts/update_faa_data.py data/aircraft.db
# Create release via GitHub CLI with database
gh release create v1.2.3 \
--title "Release v1.2.3" \
--notes "Emergency release notes here" \
data/aircraft.dbCheck:
- Workflow file exists:
.github/workflows/build-main.yml - Push was to
mainbranch - Changes weren't only to ignored paths (documentation files, etc.)
- Version step completed successfully
Fix:
- Delete the incorrect tag:
git push --delete origin v1.2.3 - Update commit messages to follow convention
- Merge again
Check:
- FAA data download successful
- Database build completed without errors
- Record count query executed successfully
Fix:
- Update
wiki/Changelog.mdwith missing information - Create a new patch release with documentation updates
Check:
-
build-main.ymlworkflow completed successfully - Docker Hub credentials are configured
- Multi-platform manifest created successfully
Check:
- Database built successfully in release workflow
- File exists at
data/aircraft.db - Upload step completed without errors
Each release contains:
- Docker image with embedded database
- Separate database artifact for download
- Statistics (record count, date) in release notes
To use a specific database version:
# Download from specific release
curl -L -o aircraft.db \
https://github.com/ryakel/tail-lookup/releases/download/v1.2.3/aircraft.db
# Or use specific Docker image
docker pull ryakel/tail-lookup:2025-11-28- Keep changelog updated - Document changes in wiki/Changelog.md as you develop
- Use semantic commits - Follow commit message conventions
- Test database changes - Verify FAA data parsing works correctly
- Test before merging - Ensure all API tests pass on develop
- Review Docker builds - Verify multi-arch images build successfully
- Monitor releases - Check GitHub releases and database stats
- Coordinate with consuming applications - Ensure API compatibility maintained
- CI/CD Pipeline - Build and deployment workflows
- Database Design - FAA database structure and schema
- API Documentation - REST API endpoints
- Deployment Guide - Deployment and integration patterns
📖 View on GitHub | 🐳 Docker Hub | 🐛 Report Issue | 💬 Discussions
License: MIT | FAA Data: Public Domain
🚀 Getting Started
📚 Documentation
🐳 Deployment
🔧 Development
🔗 Links