Skip to content

README.en.md

Latest commit

 

History

History
201 lines (159 loc) · 8.16 KB

README.en.md

File metadata and controls

201 lines (159 loc) · 8.16 KB

version-management

Centralized, reusable GitHub Actions workflow for automated versioning and release creation (Spring Boot · Next.js · Plain)
On pushes to the default branch (main) with a compliant commit message, this project performs Version bump → Project file sync → CHANGELOG update → Git Tag creation/push → GitHub Release creation (auto notes) in a standardized way.
It also emits a repository_dispatch event only when a version bump actually happens, so you can trigger follow‑up workflows (e.g., apk-build.yml) conditionally.

Korean docs → README.md

🚀 Features

  • Three project types supported
    • Spring Boot (Gradle/Groovy)
      Updates version in build.gradle, and optionally replaces the version: key in src/main/resources/application.yml.
    • Next.js (TypeScript)
      Updates package.json.version, creates/updates src/constants/version.ts (path configurable), and reflects the version in package-lock.json when present.
    • Plain (framework‑agnostic projects)
      Creates/replaces a version file (default: VERSION) so that it contains exactly one line with X.Y.Z.
      · If the file does not exist, it is created and written with X.Y.Z.
      · If it exists, it is fully overwritten and ends up with only X.Y.Z.
  • Commit‑driven versioning
    • version(major): ...
    • version(minor): ...
    • version(patch): ...
  • Policy guarantees
    • Bump only on the default branch (main)
    • Determine current version in order: Tag → Files → Default value
      · With auto detection: package.json → next, build.gradle → spring, otherwise → plain
    • CHANGELOG.md is prepended at the top (insert banner once; subsequent entries accumulate under the banner)
    • Create & push Git Tag (vX.Y.Z) + push release commit
      Release commit message: chore(release): vX.Y.Z {original subject text} [skip version]
    • No bump → workflow still succeeds (handy for pipeline branching)
  • Release & follow‑up workflow integration
    • On bump, create a GitHub Release (with auto release notes)
    • Sends repository_dispatch (default: version-bumped) only when bumped
      Payload includes: new_version, new_tag, bump_level, sha

📦 Repository layout

version-management/
├─ action.yml                        # Composite action entry (can be used directly)
├─ scripts/
│  ├─ compute-bump.mjs               # Commit inspection + version calculation
│  ├─ sync-files.mjs                 # File sync + commit (spring/next/plain)
│  ├─ update-changelog.mjs           # CHANGELOG prepend (+ initial banner)
│  └─ create-tag.mjs                 # Tag create/push + release commit handling
└─ .github/
   └─ workflows/
      └─ auto-version.yml            # Reusable workflow (workflow_call) orchestrator

Why split it like this?
The reusable workflow handles orchestration (permissions, concurrency, dispatch, release creation), while the composite action bundles the actual logic (bump/file updates/changelog/tagging) for reuse anywhere.

🧭 Quick start (consumer repo)

1) Use the reusable workflow (recommended)

Consumer repo: .github/workflows/chuseok22-version-management.yml

name: Version Management (from chuseok22/version-management)

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: write
  actions: read

jobs:
  chuseok22-version-bump:
    uses: chuseok22/version-management/.github/workflows/auto-version.yml@v1
    with:
      project_type: "auto"                 # spring | next | plain | auto
      default_branch: "main"
      tag_prefix: "v"
      default_version: "0.0.0"
      next_constants_path: "src/constants/version.ts"  # for Next.js only
      sync_app_yaml: "false"               # Spring application.yml version update
      workdir: ""                          # subdir in a monorepo, e.g., "backend"/"web"
      dispatch_on_bump: "true"             # trigger follow-ups only when bumped
      dispatch_event_type: "version-bumped"
      plain_version_file: "VERSION"        # version file path for plain projects

      # Release options
      create_release: "true"               # create a GitHub Release on bump
      release_latest: "true"               # mark as latest
      release_prerelease: "false"          # mark as prerelease (e.g., M1, RC)

2) (Advanced) Use only the logic in an existing CI

Call the composite action directly inside your job:

jobs:
  some-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 20 }

      - name: Version bump only
        uses: chuseok22/version-management@v1
        with:
          project_type: auto
          default_branch: main
          tag_prefix: v
          default_version: 0.0.0
          next_constants_path: src/constants/version.ts
          sync_app_yaml: "false"
          workdir: ""
          plain_version_file: VERSION

✍️ Commit convention (required)

Version is determined by the commit subject:

  • version(major): message → increase MAJOR (+1), reset MINOR/PATCH to 0
  • version(minor): message → increase MINOR (+1), reset PATCH to 0
  • version(patch): message → increase PATCH (+1)
  • Any other commit → no bump (workflow still succeeds)

Examples:

version(major): drop legacy API
version(minor): add CSV export
version(patch): fix null check

⚙️ Inputs (overview)

Reusable workflow .github/workflows/auto-version.yml (on: workflow_call)

Input Default Description
project_type auto spring | next | plain | auto (auto‑detect: package.json → next, build.gradle → spring, otherwise → plain)
default_branch main Only bump on this branch
tag_prefix v Tag prefix (e.g., v1.2.3)
default_version 0.0.0 Seed version when no tag/file exists
next_constants_path src/constants/version.ts Next.js constant file path
sync_app_yaml false Update version: in Spring src/main/resources/application.yml if present
workdir "" Subdirectory in a monorepo (e.g., backend, web)
dispatch_on_bump true Send repository_dispatch only when a bump occurred
dispatch_event_type version-bumped Event type for follow‑up workflows
plain_version_file VERSION Version file path for plain projects (create if missing; otherwise overwrite with a single X.Y.Z line)
create_release true Create a GitHub Release when bumped
release_latest true Mark the created release as latest
release_prerelease false Mark the created release as prerelease (M1/RC etc.)

The composite action (action.yml) accepts the same/similar inputs.

🧩 CHANGELOG policy

  • On each release, prepend a new version section to the very top.
  • On first creation, insert the banner once (future entries are added below the banner).
  • The release commit message always includes [skip version] to prevent re‑run loops.

Banner example:

<!-- vm-banner-start -->
🔧 **Version Management 자동 변경 이력**

이 파일은 중앙 배포 워크플로(**Version Management**)가 자동 생성·유지합니다.
This file is automatically generated and maintained by the centralized workflow (**Version Management**).
제작자(Author): **Chuseok22** · https://github.com/Chuseok22
워크플로 저장소(Workflow repository): https://github.com/Chuseok22/version-management

※ 절대로 이 파일을 임의로 수정하지 마세요
※ Do not edit this file manually.
<!-- vm-banner:end -->

🔒 Requirements & permissions

  • Runner: ubuntu-latest, Node: 20
  • Permissions: contents: write
  • Checkout: actions/checkout@v4 with fetch-depth: 0 (tags/history required)

Author: Chuseok22 · Repo: https://github.com/Chuseok22/version-management