> ## 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/advanced/package-development)的姊妹页面。Laravel/PHP 兼容性策略请参考[包的版本兼容性管理](/zh/advanced/package-versioning)。
</Info>

## CHANGELOG.md 的写法

CHANGELOG 是用户确认「什么变更、何时发生、在哪个版本」的一手信息。采用 [Keep a Changelog](https://keepachangelog.com/zh-CN/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、社交媒体公告之间就不容易出现偏差。
</Tip>

## 语义化版本（SemVer）

[语义化版本](https://semver.org/lang/zh-CN/)中 `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 |

请务必在 [Upgrade Guide](https://laravel.com/docs/13.x/upgrade) 中确认 Laravel 本体的升级内容。最新版发布情况可在 [laravel/framework releases](https://github.com/laravel/framework/releases) 查看。若你的包使用的 API 有破坏性变更，就需要重新设计兼容策略。

<Warning>
  提高 PHP 最低要求或删除公开 API，从用户角度看都是破坏性变更。即使与 Laravel 主版本对齐工作同时进行，也要按 MAJOR 版本发布。
</Warning>

## Git 标签与 GitHub Releases

首先打 Git 标签，并推送到 origin。

```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 标签并推送">
    以 `vX.Y.Z` 形式创建标签并推送到 `origin`。
  </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` job 设置 `needs: test` 后，测试失败时可以阻止发布。无论手动还是自动发布，都请保留这道闸门。
</Info>

## 破坏性变更的处理方式

破坏性变更应设计为可分阶段迁移。先标记废弃，在下一个 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="/zh/advanced/package-development">
    了解以 Service Provider 为中心的实现基础。
  </Card>

  <Card title="包的版本兼容性管理" icon="git-branch" href="/zh/advanced/package-versioning">
    整理 Laravel/PHP 兼容性与 SemVer 运营的判断标准。
  </Card>

  <Card title="使用 Orchestra Testbench 测试 Laravel 包" icon="flask-conical" href="/zh/advanced/package-testing">
    了解发布前所需的测试策略与实现方法。
  </Card>
</Columns>


## Related topics

- [包的版本兼容性管理](/zh/advanced/package-versioning.md)
- [如何创建 Laravel Starter Kit](/zh/advanced/starter-kit-creation.md)
- [包的静态分析（PHPStan / Larastan）](/zh/advanced/package-static-analysis.md)
- [Laravel 包开发](/zh/advanced/package-development.md)
- [Laravel Nostr](/zh/packages/laravel-nostr.md)