> ## 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 und Release-Management für Pakete

> Vom Änderungsprotokoll bis zur Automatisierung von GitHub Releases — praxisorientiertes Release-Management für die langfristige Wartung von Laravel-Paketen.

Wenn Sie ein Laravel-Paket langfristig pflegen wollen, sollten Sie zuerst Änderungsprotokoll und Release-Prozess einrichten. Ein systematisches Release-Management verhindert vergessene Ankündigungen von Breaking Changes und die Personenabhängigkeit der Release-Arbeit.

<Info>
  Diese Seite ist die Schwester von [Laravel-Paketentwicklung](/de/advanced/package-development). Zu Strategien für Laravel/PHP-Kompatibilität siehe [Versionskompatibilität von Paketen verwalten](/de/advanced/package-versioning).
</Info>

## Wie Sie CHANGELOG.md pflegen

Das CHANGELOG ist die Primärquelle, mit der Nutzer nachlesen, „was wann in welcher Version geändert wurde". Übernehmen Sie das Format von [Keep a Changelog](https://keepachangelog.com/de/1.1.0/), damit die Kategorien im Team einheitlich sind.

### Grundregeln

* Nutzen Sie das Überschriftenformat `## [x.y.z] - YYYY-MM-DD`.
* Verwenden Sie die Kategorien `Added / Changed / Deprecated / Removed / Fixed / Security`.
* Setzen Sie am Ende Compare-Links, um Diffs zu ermöglichen.
* Ungereleaste Änderungen sammeln Sie unter `## [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>
  Nutzen Sie als Release Notes einfach den passenden Versionsblock aus dem CHANGELOG. Wenn Sie die Historie in einer einzigen Quelle bündeln, driften README, GitHub Releases und Social-Media-Ankündigungen nicht auseinander.
</Tip>

## Semantic Versioning (SemVer)

[Semantic Versioning](https://semver.org/spec/v2.0.0.html) verwendet `MAJOR.MINOR.PATCH` mit folgenden Kriterien:

* **MAJOR**: Änderungen, die die Rückwärtskompatibilität brechen.
* **MINOR**: Erweiterungen unter Wahrung der Kompatibilität.
* **PATCH**: Bugfixes unter Wahrung der Kompatibilität.

### Beispiele bei Laravel-Paketen

Wie Sie Laravel-13-Support behandeln, hängt vom Inhalt der Änderung ab.

| Änderung                                                        | Empfohlene Version |
| --------------------------------------------------------------- | ------------------ |
| Laravel-12-Support behalten und zusätzlich `^13.0` unterstützen | MINOR              |
| Laravel 11/12 entfernen und nur noch `^13.0` unterstützen       | MAJOR              |
| Bugfix, der ausschließlich Laravel 13 betrifft                  | PATCH              |

Prüfen Sie die Änderungen im Laravel-Kern grundsätzlich im [Upgrade Guide](https://laravel.com/docs/13.x/upgrade). Aktuelle Releases finden Sie unter [laravel/framework releases](https://github.com/laravel/framework/releases). Enthält eine von Ihnen genutzte API Breaking Changes, überarbeiten Sie Ihre Kompatibilitätspolitik.

<Warning>
  Ein Anheben der minimalen PHP-Version oder das Entfernen öffentlicher APIs ist aus Nutzersicht ein Breaking Change. Auch wenn es zeitlich mit einem Laravel-Major-Upgrade zusammenfällt: Es ist ein MAJOR-Release.
</Warning>

## Git-Tags und GitHub Releases

Setzen Sie zunächst einen Git-Tag und pushen ihn an `origin`.

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

Wählen Sie anschließend im GitHub-Release-Editor den Tag `v2.1.0` und veröffentlichen Sie. Fügen Sie im Text den Block `## [2.1.0]` aus dem CHANGELOG ein.

<Steps>
  <Step title="Release-Commits in main mergen">
    Mergen Sie erst nach vollständig grüner Test-Pipeline in `main`.
  </Step>

  <Step title="Git-Tag erstellen und pushen">
    Erstellen Sie einen Tag im Format `vX.Y.Z` und pushen ihn nach `origin`.
  </Step>

  <Step title="GitHub Release veröffentlichen">
    Titel = Tag-Name, Text = betreffender Abschnitt aus dem CHANGELOG.
  </Step>
</Steps>

## Automatische Releases mit GitHub Actions

Mit dem Trigger `push: tags:` können Sie GitHub Releases beim Erstellen eines Tags automatisch veröffentlichen. Mit `softprops/action-gh-release` lässt sich der Inhalt des `CHANGELOG.md` direkt als Body verwenden.

```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>
  Mit `needs: test` im `release`-Job halten Sie die Veröffentlichung an, wenn Tests fehlschlagen. Behalten Sie dieses Gate — manuell wie automatisiert — unbedingt bei.
</Info>

## Umgang mit Breaking Changes

Gestalten Sie Breaking Changes so, dass eine schrittweise Migration möglich ist. Deprecaten Sie zuerst und entfernen Sie im nächsten MAJOR — das senkt den Migrationsaufwand der Nutzer.

### 1. Deprecation im Code kenntlich machen

```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. Migrationsleitfaden dokumentieren

Legen Sie in `UPGRADE.md` oder auf einer dedizierten Seite die Schritte fest, die Ihre Nutzer durchführen sollen.

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

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

### 3. Wechselnotizen zwischen Major-Versionen erhalten

Bei einem MAJOR-Upgrade verlinken Sie `Removed` im CHANGELOG und den Migrationsleitfaden gegenseitig. Nutzer sehen so „was entfernt wurde" und „wie sie es beheben" in einem Rutsch.

## Verwandte Seiten

<Columns cols={3}>
  <Card title="Laravel-Paketentwicklung" icon="box" href="/de/advanced/package-development">
    Grundlagen der Implementierung rund um Service Provider.
  </Card>

  <Card title="Versionskompatibilität von Paketen verwalten" icon="git-branch" href="/de/advanced/package-versioning">
    Entscheidungskriterien zu Laravel/PHP-Kompatibilität und SemVer-Betrieb.
  </Card>

  <Card title="Laravel-Pakete mit Orchestra Testbench testen" icon="flask-conical" href="/de/advanced/package-testing">
    Vor jedem Release notwendige Teststrategie und Umsetzung.
  </Card>
</Columns>


## Related topics

- [Laravel Package Skeleton – Starter-Template für offizielle Pakete](/de/blog/package-skeleton-introduction.md)
- [Statische Analyse für Pakete (PHPStan / Larastan)](/de/advanced/package-static-analysis.md)
- [Versionskompatibilität von Paketen verwalten](/de/advanced/package-versioning.md)
- [VOICEVOX Core für PHP](/de/packages/voicevox-core-php/index.md)
- [Queues und Jobs](/de/queues.md)