Zum Hauptinhalt springen
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.
Diese Seite ist die Schwester von Laravel-Paketentwicklung. Zu Strategien für Laravel/PHP-Kompatibilität siehe Versionskompatibilität von Paketen verwalten.

​
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, 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].
# 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
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.

​
Semantic Versioning (SemVer)

Semantic Versioning 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.
ÄnderungEmpfohlene Version
Laravel-12-Support behalten und zusätzlich ^13.0 unterstützenMINOR
Laravel 11/12 entfernen und nur noch ^13.0 unterstützenMAJOR
Bugfix, der ausschließlich Laravel 13 betrifftPATCH
Prüfen Sie die Änderungen im Laravel-Kern grundsätzlich im Upgrade Guide. Aktuelle Releases finden Sie unter laravel/framework releases. Enthält eine von Ihnen genutzte API Breaking Changes, überarbeiten Sie Ihre Kompatibilitätspolitik.
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.

​
Git-Tags und GitHub Releases

Setzen Sie zunächst einen Git-Tag und pushen ihn an origin. 
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.
1

Release-Commits in main mergen

Mergen Sie erst nach vollständig grüner Test-Pipeline in main.
2

Git-Tag erstellen und pushen

Erstellen Sie einen Tag im Format vX.Y.Z und pushen ihn nach origin.
3

GitHub Release veröffentlichen

Titel = Tag-Name, Text = betreffender Abschnitt aus dem CHANGELOG.

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

​
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

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. 
## 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

Laravel-Paketentwicklung

Grundlagen der Implementierung rund um Service Provider.

Versionskompatibilität von Paketen verwalten

Entscheidungskriterien zu Laravel/PHP-Kompatibilität und SemVer-Betrieb.

Laravel-Pakete mit Orchestra Testbench testen

Vor jedem Release notwendige Teststrategie und Umsetzung.
Zuletzt geändert am 13. Juli 2026

Verwandte Themen

Laravel Package Skeleton – Starter-Template für offizielle PaketeStatische Analyse für Pakete (PHPStan / Larastan)Versionskompatibilität von Paketen verwaltenVOICEVOX Core für PHPQueues und Jobs