패키지의 CHANGELOG와 릴리스 관리

Laravel 패키지의 변경 이력 관리에서 GitHub 릴리스의 자동화까지, 장기 유지보수에 필요한 릴리스 관리의 실전을 해설합니다.

여러분이 Laravel 패키지를 오래 유지보수하려면, 변경 이력과 릴리스 절차를 먼저 정비해 주세요. 릴리스 관리를 시스템화하면, 파괴적 변경의 주지 누락과 릴리스 작업의 속인화를 방지할 수 있습니다.

이 페이지는 Laravel 패키지 개발의 자매 페이지입니다. Laravel/PHP 호환성 전략은 패키지의 버전 호환성 관리를 참조해 주세요.

​

CHANGELOG.md 작성법

CHANGELOG는 “무엇이, 언제, 어느 버전에서 바뀌었는지”를 사용자가 확인하는 1차 정보입니다. 포맷은 Keep a Changelog를 채용하면, 카테고리 구성을 팀에서 통일할 수 있습니다.

​

기본 규칙

• ## [x.y.z] - YYYY-MM-DD 형식으로 버전을 헤딩으로 함
• Added / Changed / Deprecated / Removed / Fixed / Security를 사용함
• Compare 링크를 말미에 두어 차이를 따라갈 수 있게 함
• 아직 미릴리스된 변경은 ## [Unreleased]에 쌓음

# CHANGELOG

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Add `Package::warmCache()` for preloading metadata.

## [2.1.0] - 2026-05-10

### Added
- Add Laravel 13 support.

### Changed
- Improve default cache key generation for tagged cache stores.

### Deprecated
- Deprecate `Package::legacyHandle()` and schedule removal in v3.0.

### Fixed
- Fix null handling in `Package::resolveTenant()`.

## [2.0.0] - 2026-03-01

### Removed
- Drop Laravel 11 support.

### Security
- Harden signed URL validation against malformed host headers.

[Unreleased]: https://github.com/vendor/package/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/vendor/package/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/vendor/package/releases/tag/v2.0.0

릴리스 노트는 CHANGELOG의 해당 버전을 그대로 사용해 주세요. 이력의 정보원을 하나로 집약하면, README·GitHub Releases·SNS 공지에서 내용이 어긋나기 어려워집니다.

​

시맨틱 버저닝(SemVer)

Semantic Versioning에서는 MAJOR.MINOR.PATCH를 다음 기준으로 사용합니다.

• MAJOR: 하위 호환성을 깨는 변경(Breaking change)
• MINOR: 하위 호환성을 유지한 기능 추가
• PATCH: 하위 호환성을 유지한 버그 수정

​

Laravel 패키지에서의 판단 예

Laravel 13 대응은, 변경 내용에 따라 취급이 달라집니다.

변경	권장 버전
기존 Laravel 12 대응을 유지하면서 ^13.0을 추가	MINOR
Laravel 11/12 지원을 중단하고 ^13.0만으로 함	MAJOR
Laravel 13에서만 발생하는 결함 수정	PATCH

Laravel 본체의 업그레이드 내용은 Upgrade Guide에서 반드시 확인해 주세요. 최신판의 릴리스 상황은 laravel/framework releases에서 확인할 수 있습니다. 여러분의 패키지가 이용하는 API에 Breaking change가 있는 경우, 호환성 정책의 재설계가 필요합니다.

PHP 최저 요건의 상향이나 공개 API의 삭제는, 사용자 관점에서는 Breaking change입니다. Laravel 메이저 대응 작업과 동시라도, MAJOR 릴리스로 취급해 주세요.

​

Git 태그와 GitHub Releases

먼저 Git 태그를 붙이고, 태그를 origin에 push합니다.

git tag v2.1.0
git push origin v2.1.0

다음으로 GitHub의 Release 작성 화면에서, 태그 v2.1.0을 선택하여 공개합니다. 본문에는 CHANGELOG의 ## [2.1.0] 섹션을 붙여넣어 주세요.

1. 릴리스 대상 커밋을 main에 머지한다

   테스트가 모두 통과된 상태에서 main에 머지해 주세요.

2. Git 태그를 작성하여 push한다

   vX.Y.Z 형식의 태그를 작성하고, origin에 push합니다.

3. GitHub Release를 공개한다

   타이틀은 태그명, 본문은 CHANGELOG의 해당 항목을 사용합니다.

​

GitHub Actions에 의한 자동 릴리스

push: tags:를 트리거로 하면, 태그 작성을 기점으로 GitHub Releases를 자동 공개할 수 있습니다. softprops/action-gh-release를 사용하면, CHANGELOG.md의 내용을 직접 본문에 유용할 수 있습니다.

name: release

on:
  push:
    tags:
      - "v*.*.*"

permissions:
  contents: write

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: "8.3"
      - run: composer install --no-interaction --prefer-dist
      - run: vendor/bin/pest

  release:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Publish GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          generate_release_notes: true

release 잡에 needs: test를 설정하면, 테스트 실패 시에 공개를 멈출 수 있습니다. 수동 릴리스에서도 자동 릴리스에서도, 이 게이트는 반드시 유지해 주세요.

​

Breaking changes의 취급 방법

Breaking change는 단계적으로 이관할 수 있는 설계로 해 주세요. 우선 비추천화하고, 다음 MAJOR에서 삭제하면, 사용자의 이관 비용을 낮출 수 있습니다.

​

1. 비추천화를 코드로 표시하기

<?php

namespace Vendor\Package;

class Client
{
    /**
     * @deprecated Use handle() instead. Will be removed in v3.0.
     */
    public function legacyHandle(array $payload): array
    {
        trigger_error(
            'Client::legacyHandle() is deprecated. Use Client::handle().',
            E_USER_DEPRECATED
        );

        return $this->handle($payload);
    }

    public function handle(array $payload): array
    {
        return $payload;
    }
}

​

2. 이관 가이드를 문서화하기

UPGRADE.md 또는 전용 페이지에서, 여러분이 사용자에게 실시해 주기를 바라는 변경을 절차화해 주세요.

## Upgrading from v2 to v3

- Replace `legacyHandle()` with `handle()`.
- Update PHP to 8.3+.
- Update Laravel constraint to `^13.0`.

​

3. 메이저 버전 간의 이관 노트를 남기기

MAJOR를 올릴 때는, CHANGELOG의 Removed와 이관 가이드를 상호 링크해 주세요. 사용자는 “무엇이 삭제되었는가”와 “어떻게 고치는가”를 한 번에 따라갈 수 있습니다.

​

관련 페이지

Laravel 패키지 개발

서비스 프로바이더를 중심으로 한 구현의 기초를 확인합니다.

패키지의 버전 호환성 관리

Laravel/PHP 호환성과 SemVer 운용의 판단 기준을 정리합니다.

Orchestra Testbench로 Laravel 패키지를 테스트하기

릴리스 전에 필요한 테스트 전략과 구현 방법을 확인합니다.