> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 패키지의 CHANGELOG와 릴리스 관리

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

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

<Info>
  이 페이지는 [Laravel 패키지 개발](/ko/advanced/package-development)의 자매 페이지입니다. Laravel/PHP 호환성 전략은 [패키지의 버전 호환성 관리](/ko/advanced/package-versioning)를 참조해 주세요.
</Info>

## CHANGELOG.md 작성법

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

### 기본 규칙

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

```markdown theme={null}
# 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
```

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

## 시맨틱 버저닝(SemVer)

[Semantic Versioning](https://semver.org/spec/v2.0.0.html)에서는 `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](https://laravel.com/docs/13.x/upgrade)에서 반드시 확인해 주세요. 최신판의 릴리스 상황은 [laravel/framework releases](https://github.com/laravel/framework/releases)에서 확인할 수 있습니다. 여러분의 패키지가 이용하는 API에 Breaking change가 있는 경우, 호환성 정책의 재설계가 필요합니다.

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

## Git 태그와 GitHub Releases

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

```bash theme={null}
git tag v2.1.0
git push origin v2.1.0
```

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

<Steps>
  <Step title="릴리스 대상 커밋을 main에 머지한다">
    테스트가 모두 통과된 상태에서 `main`에 머지해 주세요.
  </Step>

  <Step title="Git 태그를 작성하여 push한다">
    `vX.Y.Z` 형식의 태그를 작성하고, `origin`에 push합니다.
  </Step>

  <Step title="GitHub Release를 공개한다">
    타이틀은 태그명, 본문은 CHANGELOG의 해당 항목을 사용합니다.
  </Step>
</Steps>

## GitHub Actions에 의한 자동 릴리스

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

```mermaid theme={null}
flowchart LR
    A["Merge to main"] --> B["Create tag<br>vX.Y.Z"]
    B --> C["GitHub Actions<br>on push tags"]
    C --> D["Run test job"]
    D --> E["Publish GitHub Release"]
```

```yaml theme={null}
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
```

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

## Breaking changes의 취급 방법

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

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

```php theme={null}
<?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` 또는 전용 페이지에서, 여러분이 사용자에게 실시해 주기를 바라는 변경을 절차화해 주세요.

```markdown theme={null}
## Upgrading from v2 to v3

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

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

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

## 관련 페이지

<Columns cols={3}>
  <Card title="Laravel 패키지 개발" icon="box" href="/ko/advanced/package-development">
    서비스 프로바이더를 중심으로 한 구현의 기초를 확인합니다.
  </Card>

  <Card title="패키지의 버전 호환성 관리" icon="git-branch" href="/ko/advanced/package-versioning">
    Laravel/PHP 호환성과 SemVer 운용의 판단 기준을 정리합니다.
  </Card>

  <Card title="Orchestra Testbench로 Laravel 패키지를 테스트하기" icon="flask-conical" href="/ko/advanced/package-testing">
    릴리스 전에 필요한 테스트 전략과 구현 방법을 확인합니다.
  </Card>
</Columns>


## Related topics

- [패키지의 버전 호환성 관리](/ko/advanced/package-versioning.md)
- [패키지의 정적 해석 (PHPStan / Larastan)](/ko/advanced/package-static-analysis.md)
- [Laravel 스타터 킷 만드는 법](/ko/advanced/starter-kit-creation.md)
- [Laravel Package Skeleton — 공식 패키지용 스타터 템플릿](/ko/blog/package-skeleton-introduction.md)
- [Orchestra Testbench로 Laravel 패키지를 테스트하기](/ko/advanced/package-testing.md)