feat: Add semantic versioning workflow with conventional commits and fix wiki history preservation #8

Copilot · 2025-08-29T20:29:44Z

This PR implements automated semantic versioning for QueryPal using conventional commits, addressing the requirement to calculate software version numbers automatically when the production branch is updated.

Overview

The implementation provides a complete semantic versioning solution that:

Automatically calculates version numbers based on conventional commit messages
Creates Git tags following the vX.Y.Z format starting from v2.0.0
Updates the project wiki with release information while preserving complete history
Maintains CHANGELOG.md with auto-generated release notes
Integrates seamlessly with the existing Google Cloud Run deployment workflow

Key Features

🤖 Automated Version Calculation

MAJOR (X.y.z): Breaking changes (feat!:, BREAKING CHANGE:)
MINOR (x.Y.z): New features (feat:)
PATCH (x.y.Z): Bug fixes, docs, refactoring (fix:, docs:, etc.)

🏷️ Smart Tag Handling

Handles the existing v2.0 tag by creating a compatible v2.0.0 semantic version
All future releases follow proper semantic versioning format

📚 Documentation & Wiki Updates

Auto-generates release notes from commit messages
Updates project wiki with deployment information and change summaries
Preserves complete release history without overwriting previous releases
Maintains CHANGELOG.md with structured release history

🔄 Workflow Integration

Triggers on production branch pushes (same as deployment workflow)
Semantic release runs first, then deployment can reference created tags
Can be manually triggered via workflow dispatch

Wiki History Preservation Fix

A critical fix ensures the wiki Releases.md file properly maintains historical releases. The original implementation had a flawed backup system that:

Overwrote the entire file on each release
Only preserved the immediate previous release
Lost cumulative release history over time

The fix ensures:

Complete history preservation across all releases
Proper migration of current "Latest Release" to "Previous Release" format
No reliance on backup files that could fail or be incomplete

Implementation Details

Files Added/Modified

New Workflow: .github/workflows/semantic-release.yml

Uses semantic-release with conventional changelog plugins
Configures commit analysis rules and release note generation
Handles wiki updates with proper history preservation

Documentation:

docs/SEMANTIC_VERSIONING.md - Comprehensive guide for developers
CHANGELOG.md - Initial changelog structure
README.md - Added versioning section with links to documentation

Conventional Commit Examples

# Minor version bump (2.0.0 → 2.1.0)
feat: add user authentication system

# Patch version bump (2.0.0 → 2.0.1)  
fix: resolve login timeout issue

# Major version bump (2.0.0 → 3.0.0)
feat!: redesign user API with breaking changes

Testing & Validation

✅ YAML workflow syntax validated
✅ Semantic-release dependencies tested locally
✅ Tag handling logic verified for v2.0 → v2.0.0 transition
✅ Wiki history preservation logic tested and validated
✅ Conventional commit parsing tested with real repository history

Expected Behavior

Based on current commits since v2.0, the next release will be v2.1.0 due to the feat: commits in this PR. Future releases will be automatically calculated based on conventional commit types.

The workflow integrates perfectly with the existing deployment process - when code is pushed to production, it will:

Analyze commits and create version tag
Update wiki with cumulative release history preserved
Update changelog
Trigger the existing Cloud Run deployment with the new version

This provides complete traceability from commits → versions → deployments → release documentation with full historical context maintained.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: ChingEnLin <[email protected]>

Copilot

Pull Request Overview

This PR implements automated semantic versioning for QueryPal using conventional commits to automatically calculate version numbers when the production branch is updated.

Adds semantic-release workflow with GitHub Actions integration
Implements comprehensive documentation for conventional commit standards and versioning process
Establishes automated changelog management and wiki updates for release tracking

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
`.github/workflows/semantic-release.yml`	Complete workflow implementation for automated versioning, release creation, and wiki updates
`docs/SEMANTIC_VERSIONING.md`	Detailed documentation covering conventional commit standards, version bump rules, and workflow processes
`README.md`	Added versioning section with links to semantic versioning documentation
`CHANGELOG.md`	Initial changelog structure following Keep a Changelog format

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-08-30T07:33:26Z

.github/workflows/semantic-release.yml

+          if [ -f "Releases.md.bak" ]; then
+            # Extract previous releases section if it exists
+            grep -A 1000 "### Previous Releases" "Releases.md.bak" | tail -n +2 >> "Releases.md" 2>/dev/null || true
+          fi


The logic tries to read from 'Releases.md.bak' before it's created. Since the backup is only created at line 242, this condition will always be false on first run, potentially losing previous releases data if the file already exists.

Copilot · 2025-08-30T07:33:27Z

.github/workflows/semantic-release.yml

+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          # Create or update the Releases page
+          cat > "Releases.md" << EOF


The wiki page creation overwrites the entire 'Releases.md' file, potentially losing existing release history. Consider reading the existing file first and preserving the 'Previous Releases' section before recreating it.

ChingEnLin · 2025-08-30T07:54:16Z

@copilot fix the wiki page creation overwriting entire releases.md file issue, check the comments

- Read existing Releases.md before overwriting to preserve all history - Convert current "Latest Release" to "Previous Release" format - Remove faulty backup approach that only kept one previous release - Ensure cumulative release history is maintained across all updates Co-authored-by: ChingEnLin <[email protected]>

Copilot · 2025-08-30T07:58:22Z

@copilot fix the wiki page creation overwriting entire releases.md file issue, check the comments

Fixed the wiki page creation issue. The problem was the workflow was completely overwriting the Releases.md file each time and relying on a faulty backup system that only preserved the immediate previous release.

The fix (commit 85c8e31) now:

Reads the existing Releases.md before overwriting it
Preserves all previous release history
Converts the current "Latest Release" to a proper "Previous Release" entry
Maintains cumulative history across all future releases

This ensures no release history is lost when new versions are published.

github-actions · 2025-09-01T13:29:31Z

🎉 This PR is included in version 2.1.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Initial plan

fe0fa20

Copilot AI assigned Copilot and ChingEnLin Aug 29, 2025

Copilot started work on behalf of ChingEnLin August 29, 2025 20:29 View session

Copilot AI and others added 2 commits August 29, 2025 20:34

feat: Add semantic versioning workflow with conventional commits

13dbed7

Co-authored-by: ChingEnLin <[email protected]>

docs: Add semantic versioning documentation and README updates

a843509

Co-authored-by: ChingEnLin <[email protected]>

Copilot AI requested a review from ChingEnLin August 29, 2025 20:39

Copilot finished work on behalf of ChingEnLin August 29, 2025 20:39

ChingEnLin marked this pull request as ready for review August 30, 2025 07:32

Copilot AI review requested due to automatic review settings August 30, 2025 07:32

Copilot AI reviewed Aug 30, 2025

View reviewed changes

Copilot started work on behalf of ChingEnLin August 30, 2025 07:54 View session

Copilot AI changed the title ~~feat: Add semantic versioning workflow with conventional commits~~ feat: Add semantic versioning workflow with conventional commits and fix wiki history preservation Aug 30, 2025

Copilot finished work on behalf of ChingEnLin August 30, 2025 07:59

ChingEnLin merged commit 0229ae5 into dev Aug 30, 2025

ChingEnLin deleted the copilot/fix-8e58a13a-b75c-438a-93cf-4b269c74beda branch August 30, 2025 08:34

github-actions bot added the released label Sep 1, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add semantic versioning workflow with conventional commits and fix wiki history preservation #8

feat: Add semantic versioning workflow with conventional commits and fix wiki history preservation #8

Uh oh!

Copilot AI commented Aug 29, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Aug 30, 2025

Uh oh!

Copilot AI Aug 30, 2025

Uh oh!

ChingEnLin commented Aug 30, 2025

Uh oh!

Copilot AI commented Aug 30, 2025

Uh oh!

github-actions bot commented Sep 1, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: Add semantic versioning workflow with conventional commits and fix wiki history preservation #8

feat: Add semantic versioning workflow with conventional commits and fix wiki history preservation #8

Uh oh!

Conversation

Copilot AI commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Key Features

🤖 Automated Version Calculation

🏷️ Smart Tag Handling

📚 Documentation & Wiki Updates

🔄 Workflow Integration

Wiki History Preservation Fix

Implementation Details

Files Added/Modified

Conventional Commit Examples

Testing & Validation

Expected Behavior

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Aug 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 30, 2025

Choose a reason for hiding this comment

Uh oh!

ChingEnLin commented Aug 30, 2025

Uh oh!

Copilot AI commented Aug 30, 2025

Uh oh!

github-actions bot commented Sep 1, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Aug 29, 2025 •

edited

Loading