Versioning and Releases

Versioning & Releases

Automated semantic versioning and GitHub releases for the Firebase React Template.

Overview

This project uses automated semantic versioning with GitHub Actions. Every merge to the main branch automatically:

1. ✅ Determines version bump type from commit messages
2. ✅ Creates a new Git tag (v1.0.0 → v1.0.1 → v1.0.2)
3. ✅ Updates package.json version
4. ✅ Builds the project
5. ✅ Creates a GitHub Release with archives
6. ✅ Generates release notes from commits

graph TD
    A[Merge to main] --> B{Analyze Commit Message}
    B -->|breaking:| C[Major v1.0.0 → v2.0.0]
    B -->|feat:| D[Minor v1.0.0 → v1.1.0]
    B -->|Other| E[Patch v1.0.0 → v1.0.1]
    C --> F[Create Git Tag]
    D --> F
    E --> F
    F --> G[Update package.json]
    G --> H[Build Project]
    H --> I[Create Archives]
    I --> J[Generate Release Notes]
    J --> K[Publish GitHub Release]

Loading

---

Semantic Versioning

Version Format

Versions follow semantic versioning (SemVer): vMAJOR.MINOR.PATCH

• MAJOR (v1.0.0 → v2.0.0): Breaking changes
• MINOR (v1.0.0 → v1.1.0): New features (backward compatible)
• PATCH (v1.0.0 → v1.0.1): Bug fixes (backward compatible)

Version Bump Rules

The version bump type is determined by your commit message prefix:

Commit Prefix	Version Bump	Example	Description
breaking: or major:	MAJOR	v1.0.0 → v2.0.0	Breaking changes
feat: or feature: or minor:	MINOR	v1.0.0 → v1.1.0	New features
All others	PATCH	v1.0.0 → v1.0.1	Bug fixes, docs, etc.

---

Commit Message Convention

Format

<type>: <description>

[optional body]

[optional footer]

Examples

Patch Release (v1.0.0 → v1.0.1)

git commit -m "fix: resolve authentication timeout issue"
git commit -m "docs: update setup guide"
git commit -m "style: format code with prettier"
git commit -m "chore: update dependencies"

Minor Release (v1.0.0 → v1.1.0)

git commit -m "feat: add dark mode toggle"
git commit -m "feature: implement user profile page"
git commit -m "minor: add email verification"

Major Release (v1.0.0 → v2.0.0)

git commit -m "breaking: change authentication API structure"
git commit -m "major: migrate to Firebase v10"

---

Automated Release Process

Workflow Diagram

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub
    participant Actions as GitHub Actions
    participant Releases as GitHub Releases

    Dev->>GH: Push to main branch
    GH->>Actions: Trigger release workflow
    Actions->>Actions: Get latest tag (v1.0.0)
    Actions->>Actions: Analyze commit message
    Actions->>Actions: Calculate new version (v1.0.1)
    Actions->>Actions: Update package.json
    Actions->>Actions: Build project
    Actions->>Actions: Create source archive
    Actions->>Actions: Create build archive
    Actions->>Actions: Generate checksums
    Actions->>GH: Create Git tag (v1.0.1)
    Actions->>Actions: Generate release notes
    Actions->>Releases: Create GitHub Release
    Releases->>Dev: ✅ Release published

Loading

What Gets Created

When you merge to main, the workflow automatically creates:

1. Git Tag: v1.0.1, v1.0.2, etc.
2. GitHub Release: With title "Release v1.0.1"
3. Release Assets:
   • firebase-react-template-v1.0.1-source.tar.gz - Full source code
   • firebase-react-template-v1.0.1-build.tar.gz - Production build
   • checksums.txt - SHA256 checksums for verification

---

Manual Version Bumping

Using the Bump Version Script

The project includes a shell script for manual version bumping:

# Bump patch version (v1.0.0 → v1.0.1)
bash .github/scripts/bump-version.sh patch

# Bump minor version (v1.0.0 → v1.1.0)
bash .github/scripts/bump-version.sh minor

# Bump major version (v1.0.0 → v2.0.0)
bash .github/scripts/bump-version.sh major

Manual Tagging

If you need to create a tag manually:

# Create and push a tag
git tag -a v1.0.1 -m "Release v1.0.1"
git push origin v1.0.1

# Update package.json to match
npm version 1.0.1 --no-git-tag-version
git add package.json package-lock.json
git commit -m "chore: bump version to v1.0.1"
git push

---

Viewing Releases

GitHub Releases Page

Visit: https://github.com/ThanuMahee12/firebase-react-template/releases

Each release includes:

• 📝 Auto-generated release notes from commits
• 📦 Downloadable source code archives
• 🏗️ Pre-built production files
• ✅ SHA256 checksums for verification
• 📅 Release date and tag information

Latest Release Badge

Add to README:

[![Latest Release](https://img.shields.io/github/v/release/ThanuMahee12/firebase-react-template)](https://github.com/ThanuMahee12/firebase-react-template/releases)

---

Release Assets

Source Code Archive

File: firebase-react-template-v1.0.1-source.tar.gz

Contains the complete template source code (excludes node_modules, .git, dist).

Download and extract:

# Download from GitHub Releases
wget https://github.com/ThanuMahee12/firebase-react-template/releases/download/v1.0.1/firebase-react-template-v1.0.1-source.tar.gz

# Extract
tar -xzf firebase-react-template-v1.0.1-source.tar.gz

# Install and run
cd firebase-react-template
npm install
npm run dev

Production Build Archive

File: firebase-react-template-v1.0.1-build.tar.gz

Contains pre-built production files ready for deployment.

Download and deploy:

# Download from GitHub Releases
wget https://github.com/ThanuMahee12/firebase-react-template/releases/download/v1.0.1/firebase-react-template-v1.0.1-build.tar.gz

# Extract to Firebase hosting directory
tar -xzf firebase-react-template-v1.0.1-build.tar.gz -C dist/

# Deploy to Firebase
firebase deploy --only hosting

Checksums Verification

File: checksums.txt

Verify download integrity:

# Download checksums file
wget https://github.com/ThanuMahee12/firebase-react-template/releases/download/v1.0.1/checksums.txt

# Verify source archive
sha256sum -c checksums.txt --ignore-missing

---

Version History

Viewing All Tags

# List all tags
git tag

# List tags with messages
git tag -n

# Show tag details
git show v1.0.1

Checking Out Specific Versions

# Checkout a specific version
git checkout v1.0.1

# Create a branch from a version
git checkout -b fix/from-v1.0.1 v1.0.1

# Return to latest
git checkout main

---

Troubleshooting

Release Workflow Failed

Problem: GitHub Actions release workflow fails

Solutions:

1. Check permissions:

   • Go to Settings → Actions → General
   • Under "Workflow permissions", select "Read and write permissions"

2. Verify commit message format:

   # Use proper commit format
   git commit -m "feat: add new feature"

3. Check build errors:

   # Test build locally before pushing
   npm run build

Tag Already Exists

Problem: Trying to create a tag that already exists

Solution:

# Delete local tag
git tag -d v1.0.1

# Delete remote tag
git push origin :refs/tags/v1.0.1

# Recreate tag
git tag -a v1.0.1 -m "Release v1.0.1"
git push origin v1.0.1

Version Mismatch

Problem: package.json version doesn't match Git tag

Solution:

# Get current tag
CURRENT_TAG=$(git describe --tags --abbrev=0)
VERSION=${CURRENT_TAG#v}

# Update package.json
npm version $VERSION --no-git-tag-version

# Commit the change
git add package.json package-lock.json
git commit -m "chore: sync version with tag $CURRENT_TAG"
git push

---

Best Practices

1. Use Conventional Commits

Always prefix commits with type indicators:

# Good
git commit -m "feat: add user profile page"
git commit -m "fix: resolve login redirect issue"

# Bad (will default to patch)
git commit -m "added new feature"
git commit -m "bug fix"

2. Test Before Merging

Before merging to main:

# Run all checks
npm run format:check
npm run lint
npm run build
npm run preview

3. Write Descriptive Commit Messages

Good commit messages help generate useful release notes:

# Good - descriptive
git commit -m "feat: add Firebase authentication with Google Sign-In"

# Bad - vague
git commit -m "feat: update auth"

4. Group Related Changes

Don't merge multiple unrelated features at once:

# Good - single feature
git commit -m "feat: add dark mode toggle to settings"

# Bad - multiple features
git commit -m "feat: add dark mode, user profile, and notification system"

5. Review Release Notes

After a release is created:

• Check the auto-generated release notes
• Edit if necessary on GitHub
• Add additional context if needed

---

Workflow Configuration

Release Workflow File

Location: .github/workflows/release.yml

Key Features:

• Auto-detects version bump type
• Updates package.json automatically
• Creates source and build archives
• Generates SHA256 checksums
• Auto-generates release notes from commits

Version Bump Script

Location: .github/scripts/bump-version.sh

Usage:

bash .github/scripts/bump-version.sh [major|minor|patch]

Features:

• Reads latest Git tag
• Calculates next version
• Supports all SemVer bump types
• Compatible with GitHub Actions

---

Integration with CI/CD

Combined Deploy and Release

The release workflow works alongside the deployment workflow:

graph TD
    A[Push to main] --> B[Deploy Workflow]
    A --> C[Release Workflow]
    B --> D[Format Check]
    D --> E[Lint Check]
    E --> F[Build]
    F --> G[Deploy to Firebase]
    C --> H[Calculate Version]
    H --> I[Create Tag]
    I --> J[Build Project]
    J --> K[Create Release]
    K --> L[Upload Archives]

Loading

Both workflows run independently and in parallel.

---

Related Documentation

• GitHub Actions - CI/CD setup
• Deployment Guide - Deployment process
• Development Workflow - Daily development

---

Next: GitHub Actions →