> ## 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 Release 的自動化，說明長期維護所需的發布管理實務。

若您要長期維護 Laravel 套件，請先整備變更歷史與發布程序。將發布管理機制化，可避免破壞性變更遺漏公告、以及發布作業屬人化。

<Info>
  本頁為[Laravel 套件開發](/zh-TW/advanced/package-development)的姊妹頁。Laravel/PHP 相容性策略請參考[套件的版本相容性管理](/zh-TW/advanced/package-versioning)。
</Info>

## CHANGELOG.md 的寫法

CHANGELOG 是使用者確認「什麼、於何時、於哪個版本變動」的一手資訊。若採用 [Keep a Changelog](https://keepachangelog.com/zh-TW/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>
  Release Notes 請直接沿用 CHANGELOG 對應版本。將歷史資訊來源集中於一處，可讓 README、GitHub Releases 與 SNS 公告內容不易失準。
</Tip>

## Semantic Versioning（SemVer）

[Semantic Versioning](https://semver.org/spec/v2.0.0.html) 中的 `MAJOR.MINOR.PATCH` 依下列基準使用。

* **MAJOR**：破壞後向相容性的變更（Breaking change）
* **MINOR**：保持後向相容性的功能新增
* **PATCH**：保持後向相容性的 bug 修正

### Laravel 套件的判斷範例

Laravel 13 的支援，會依變更內容有不同處理。

| 變更                             | 建議版本  |
| ------------------------------ | ----- |
| 保留既有 Laravel 12 支援並加入 `^13.0`  | MINOR |
| 終止 Laravel 11/12 支援僅保留 `^13.0` | MAJOR |
| 僅於 Laravel 13 發生的 bug 修正       | 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 release。
</Warning>

## Git tag 與 GitHub Releases

先建立 Git tag，並 push 至 origin。

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

接著於 GitHub 的 Release 建立畫面選擇 tag `v2.1.0` 並公開。本文請貼上 CHANGELOG 的 `## [2.1.0]` 段落。

<Steps>
  <Step title="將 Release 對象 commit merge 至 main">
    於測試全部通過的狀態下 merge 至 `main`。
  </Step>

  <Step title="建立 Git tag 並 push">
    建立 `vX.Y.Z` 格式的 tag，push 至 `origin`。
  </Step>

  <Step title="公開 GitHub Release">
    標題使用 tag 名，本文使用 CHANGELOG 對應項目。
  </Step>
</Steps>

## 使用 GitHub Actions 自動化發布

以 `push: tags:` 作為觸發，可以 tag 建立為起點自動公開 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` job 設定 `needs: test` 後，測試失敗時可阻止公開。無論手動或自動 release，此 gate 皆應維持。
</Info>

## Breaking changes 的處理方式

請將 Breaking change 設計為可分階段遷移。先標示為 deprecated，再於下一個 MAJOR 刪除，可降低使用者的遷移成本。

### 1. 於程式碼中標示 deprecated

```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="/zh-TW/advanced/package-development">
    確認以服務提供者為核心的實作基礎。
  </Card>

  <Card title="套件的版本相容性管理" icon="git-branch" href="/zh-TW/advanced/package-versioning">
    整理 Laravel/PHP 相容性與 SemVer 運用的判斷基準。
  </Card>

  <Card title="以 Orchestra Testbench 測試 Laravel 套件" icon="flask-conical" href="/zh-TW/advanced/package-testing">
    確認發布前所需的測試策略與實作方式。
  </Card>
</Columns>


## Related topics

- [套件的版本相容性管理](/zh-TW/advanced/package-versioning.md)
- [Laravel 啟動套件的建立方式](/zh-TW/advanced/starter-kit-creation.md)
- [我的套件](/zh-TW/packages/index.md)
- [套件的靜態分析（PHPStan / Larastan）](/zh-TW/advanced/package-static-analysis.md)
- [Laravel Nostr](/zh-TW/packages/laravel-nostr.md)