> ## 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 en releasebeheer voor packages

> Van het bijhouden van wijzigingen in Laravel-packages tot het automatiseren van GitHub-releases: de releasepraktijk die je nodig hebt voor langdurig onderhoud.

Als je een Laravel-package langdurig onderhoudt, richt dan eerst je changelog en releaseprocedure in. Door releasebeheer te systematiseren voorkom je dat breaking changes onopgemerkt blijven en dat releasewerk afhankelijk wordt van één persoon.

<Info>
  Deze pagina is een zusterpagina van [Laravel-packages ontwikkelen](/nl/advanced/package-development). Zie voor strategieën rond Laravel/PHP-compatibiliteit [Versiecompatibiliteit van packages beheren](/nl/advanced/package-versioning).
</Info>

## CHANGELOG.md schrijven

De changelog is de primaire bron waarin gebruikers nakijken "wat er wanneer en in welke versie is veranderd". Als je het formaat van [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) aanhoudt, kun je de categorie-indeling binnen je team uniform houden.

### Basisregels

* Gebruik versies als kop in het formaat `## [x.y.z] - YYYY-MM-DD`
* Gebruik `Added / Changed / Deprecated / Removed / Fixed / Security`
* Zet compare-links onderaan zodat je de diff kunt volgen
* Zet nog niet uitgebrachte wijzigingen onder `## [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>
  Gebruik voor releasenotes de betreffende versie uit de changelog ongewijzigd. Door de historie bij één bron te houden, lopen README, GitHub Releases en aankondigingen op sociale media minder snel uit elkaar.
</Tip>

## Semantische versionering (SemVer)

Bij [Semantic Versioning](https://semver.org/spec/v2.0.0.html) gebruik je `MAJOR.MINOR.PATCH` volgens deze criteria:

* **MAJOR**: wijzigingen die de achterwaartse compatibiliteit breken (breaking change)
* **MINOR**: functietoevoegingen met behoud van achterwaartse compatibiliteit
* **PATCH**: bugfixes met behoud van achterwaartse compatibiliteit

### Beslisvoorbeelden voor Laravel-packages

Hoe je Laravel 13-ondersteuning behandelt, hangt af van de inhoud van de wijziging.

| Wijziging                                                           | Aanbevolen versie |
| ------------------------------------------------------------------- | ----------------- |
| `^13.0` toevoegen met behoud van bestaande Laravel 12-ondersteuning | MINOR             |
| Laravel 11/12-ondersteuning stopzetten en alleen `^13.0` overhouden | MAJOR             |
| Bugfix voor een probleem dat alleen op Laravel 13 optreedt          | PATCH             |

Controleer de upgrade-inhoud van Laravel zelf altijd in de [Upgrade Guide](https://laravel.com/docs/13.x/upgrade). De releasestatus van de nieuwste versie vind je bij [laravel/framework releases](https://github.com/laravel/framework/releases). Als er breaking changes zitten in de API's die jouw package gebruikt, moet je je compatibiliteitsbeleid herzien.

<Warning>
  Het verhogen van de minimale PHP-vereiste of het verwijderen van publieke API's is vanuit het perspectief van gebruikers een breaking change. Behandel dit als een MAJOR-release, ook als het samenvalt met werk voor een Laravel-major.
</Warning>

## Git-tags en GitHub Releases

Maak eerst een Git-tag en push die naar origin.

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

Selecteer vervolgens in het releasescherm van GitHub de tag `v2.1.0` en publiceer de release. Plak in de beschrijving de sectie `## [2.1.0]` uit de changelog.

<Steps>
  <Step title="Merge de release-commit naar main">
    Merge naar `main` in een staat waarin alle tests slagen.
  </Step>

  <Step title="Maak een Git-tag en push die">
    Maak een tag in het formaat `vX.Y.Z` en push die naar `origin`.
  </Step>

  <Step title="Publiceer de GitHub Release">
    Gebruik de tagnaam als titel en het betreffende changelog-item als beschrijving.
  </Step>
</Steps>

## Automatische releases met GitHub Actions

Met `push: tags:` als trigger kun je GitHub Releases automatisch publiceren zodra er een tag wordt aangemaakt. Met `softprops/action-gh-release` kun je de inhoud van `CHANGELOG.md` rechtstreeks hergebruiken als beschrijving.

```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>
  Door `needs: test` op de `release`-job te zetten, kun je de publicatie tegenhouden als tests falen. Houd deze gate altijd in stand, of je nu handmatig of automatisch releaset.
</Info>

## Omgaan met breaking changes

Ontwerp breaking changes zo dat gebruikers stapsgewijs kunnen migreren. Door iets eerst te deprecaten en pas in de volgende MAJOR te verwijderen, verlaag je de migratiekosten voor gebruikers.

### 1. Maak de deprecatie zichtbaar in de code

```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. Documenteer een migratiegids

Beschrijf in `UPGRADE.md` of op een aparte pagina stap voor stap welke wijzigingen je van gebruikers verwacht.

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

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

### 3. Laat migratienotities achter tussen majorversies

Wanneer je de MAJOR verhoogt, link dan de `Removed`-sectie van de changelog en de migratiegids naar elkaar. Gebruikers kunnen dan in één keer nagaan "wat er is verwijderd" en "hoe ze het oplossen".

## Gerelateerde pagina's

<Columns cols={3}>
  <Card title="Laravel-packages ontwikkelen" icon="box" href="/nl/advanced/package-development">
    Bekijk de basis van een implementatie rond service providers.
  </Card>

  <Card title="Versiecompatibiliteit van packages beheren" icon="git-branch" href="/nl/advanced/package-versioning">
    Zet de beslissingscriteria voor Laravel/PHP-compatibiliteit en SemVer op een rij.
  </Card>

  <Card title="Laravel-packages testen met Orchestra Testbench" icon="flask-conical" href="/nl/advanced/package-testing">
    Bekijk de teststrategie en implementatie die je vóór een release nodig hebt.
  </Card>
</Columns>


## Related topics

- [Laravel Package Skeleton — officiële startertemplate voor packages](/nl/blog/package-skeleton-introduction.md)
- [Versiecompatibiliteit van packages beheren](/nl/advanced/package-versioning.md)
- [Laravel-updates van augustus 2026](/nl/blog/changelog/202608.md)
- [Laravel-updates van april 2026](/nl/blog/changelog/202604.md)
- [Laravel-updates van maart 2026](/nl/blog/changelog/202603.md)