Skip to content

Semantic Versioning & Release Best Practices

CupOfTea adheres to Semantic Versioning 2.0.0 and follows Keep a Changelog.

Current Version: v0.2.0

1. Version Format: MAJOR.MINOR.PATCH

Component Trigger Example
MAJOR Incompatible API changes, removals, breaking behavior 1.0.0 → 2.0.0
MINOR Backwards-compatible new features, aggregations, formats 0.2.0 → 0.3.0
PATCH Backwards-compatible bug fixes and performance tuning 0.2.0 → 0.2.1

2. Commit Best Practices (Conventional Commits)

Use structured prefix messages:

  • feat(scope): ... → New feature (MINOR)
  • fix(scope): ... → Bug fix (PATCH)
  • perf(scope): ... → Performance optimization (PATCH)
  • feat(scope)!: ... or BREAKING CHANGE: ... → Breaking change (MAJOR)
  • docs(scope): ... → Documentation only
  • refactor(scope): ... → Code refactoring without behavior change
  • test(scope): ... → Adding or modifying unit/integration tests
  • chore(scope): ... → Build configuration, dependencies, or tooling

3. How to Release a New Version

  1. Bump Version Across POMs: Update pom.xml in the root and all 9 module folders: 

    # Or via Maven Versions Plugin:
mvn versions:set -DnewVersion=0.3.0 -DgenerateBackupPoms=false

  2. Update CHANGELOG.md: Add a new section for the release: 

    ## [0.3.0] - YYYY-MM-DD

### Added
- Description of new features...

  3. Merge into Main/Master: When merged into master (or main), the automated GitHub Actions workflow (.github/workflows/release.yml) will:

  4. Verify the version in pom.xml (0.3.0).
  5. Automatically tag v0.3.0.
  6. Identify the previous tag and collect all changes in between (commits, PRs, and changelog highlights via .github/scripts/generate-release-notes.py).
  7. Build all module JAR packages.
  8. Publish the GitHub Release with the complete release notes and attached binaries.

4. Pull Request Requirements (Merge Gate)

GitHub Actions runs .github/workflows/semver-check.yml on every Pull Request targeting develop, master, or main.

A PR will be blocked from merging if: 1. Version is not updated: The version in pom.xml matches the base branch. 2. Version is not strictly greater: The new version is lower than the base branch version (new_version <= base_version). 3. Submodule version mismatch: Any of the 9 reactor submodules (cupoftea-core, cupoftea-csv, etc.) differs from the root pom.xml. 4. Missing Changelog: No entry corresponding to the new version exists in CHANGELOG.md.