> ## 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 et gestion des releases de packages

> De la gestion de l'historique des changements à l'automatisation des releases GitHub, découvrez les pratiques indispensables à la maintenance long terme d'un package Laravel.

Si vous souhaitez maintenir longtemps un package Laravel, mettez en place au préalable l'historique des changements et le processus de release. Systématiser la gestion des releases évite les oublis de communication autour des changements cassants et empêche le processus de dépendre d'une seule personne.

<Info>
  Cette page est la sœur de [Développement de packages Laravel](/fr/advanced/package-development). Pour la stratégie de compatibilité Laravel/PHP, consultez [Gestion de la compatibilité de versions de package](/fr/advanced/package-versioning).
</Info>

## Rédiger le CHANGELOG.md

Le CHANGELOG est l'information de première main permettant à vos utilisateurs de vérifier « ce qui a changé, quand et dans quelle version ». En adoptant le format [Keep a Changelog](https://keepachangelog.com/fr/1.1.0/), vous uniformisez au sein de l'équipe la structure des catégories.

### Règles de base

* Utilisez le titre `## [x.y.z] - YYYY-MM-DD` pour chaque version.
* Utilisez les catégories `Added / Changed / Deprecated / Removed / Fixed / Security`.
* Placez les liens Compare en pied de fichier pour permettre de suivre les diffs.
* Empilez les changements non encore publiés sous `## [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>
  Réutilisez telle quelle la section correspondante du CHANGELOG comme notes de release. Centraliser la source d'information réduit le risque d'écarts entre le README, les GitHub Releases et les annonces sur les réseaux sociaux.
</Tip>

## Versionnement sémantique (SemVer)

Le [Semantic Versioning](https://semver.org/lang/fr/) utilise `MAJOR.MINOR.PATCH` selon les critères suivants :

* **MAJOR** : changement qui rompt la rétrocompatibilité (Breaking change).
* **MINOR** : ajout de fonctionnalité rétrocompatible.
* **PATCH** : correction de bug rétrocompatible.

### Exemples de décision pour un package Laravel

Le traitement d'un support Laravel 13 varie selon la nature du changement.

| Changement                                                       | Version recommandée |
| ---------------------------------------------------------------- | ------------------- |
| Maintien du support Laravel 12 existant tout en ajoutant `^13.0` | MINOR               |
| Abandon du support Laravel 11/12 et ne conserver que `^13.0`     | MAJOR               |
| Correction d'un bug ne survenant qu'avec Laravel 13              | PATCH               |

Le contenu de la montée de version de Laravel se vérifie impérativement dans l'[Upgrade Guide](https://laravel.com/docs/13.x/upgrade). L'état de la dernière release est consultable sur [laravel/framework releases](https://github.com/laravel/framework/releases). Si les API utilisées par votre package subissent un changement cassant, votre politique de compatibilité doit être revue.

<Warning>
  Relever la version PHP minimale requise ou supprimer une API publique constitue un changement cassant du point de vue des utilisateurs. Même si le travail se fait en même temps que la mise à jour majeure de Laravel, traitez-le comme une release MAJOR.
</Warning>

## Tags Git et GitHub Releases

Créez d'abord un tag Git, puis poussez-le vers origin.

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

Ensuite, dans l'écran de création de Release GitHub, sélectionnez le tag `v2.1.0` et publiez. Copiez la section `## [2.1.0]` du CHANGELOG dans le corps.

<Steps>
  <Step title="Fusionner le commit cible dans main">
    Fusionnez sur `main` alors que tous les tests sont au vert.
  </Step>

  <Step title="Créer et pousser le tag Git">
    Créez un tag au format `vX.Y.Z` et poussez-le vers `origin`.
  </Step>

  <Step title="Publier la GitHub Release">
    Utilisez le nom du tag comme titre et la section correspondante du CHANGELOG comme corps.
  </Step>
</Steps>

## Release automatique via GitHub Actions

Déclencher sur `push: tags:` permet d'automatiser la publication de la GitHub Release dès la création d'un tag. Avec `softprops/action-gh-release`, vous pouvez injecter directement le contenu du `CHANGELOG.md` dans le corps.

```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>
  Ajouter `needs: test` au job `release` permet d'empêcher la publication en cas d'échec des tests. Que la release soit manuelle ou automatique, conservez impérativement cette barrière.
</Info>

## Gérer les Breaking changes

Concevez les changements cassants pour permettre une migration progressive. En dépréciant d'abord puis en supprimant à la MAJOR suivante, vous réduisez le coût de migration pour vos utilisateurs.

### 1. Signaler la dépréciation dans le 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. Documenter le guide de migration

Dans `UPGRADE.md` ou une page dédiée, décrivez pas à pas les changements que vous demandez aux utilisateurs.

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

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

### 3. Laisser des notes de migration entre versions majeures

Lors d'une montée de MAJOR, liez mutuellement la section `Removed` du CHANGELOG et le guide de migration. Les utilisateurs peuvent alors suivre en une seule fois « ce qui a été supprimé » et « comment corriger ».

## Pages associées

<Columns cols={3}>
  <Card title="Développement de packages Laravel" icon="box" href="/fr/advanced/package-development">
    Passez en revue les fondations de l'implémentation autour du service provider.
  </Card>

  <Card title="Gestion de la compatibilité de versions de package" icon="git-branch" href="/fr/advanced/package-versioning">
    Structurez vos critères de décision autour de la compatibilité Laravel/PHP et l'usage de SemVer.
  </Card>

  <Card title="Tester des packages Laravel avec Orchestra Testbench" icon="flask-conical" href="/fr/advanced/package-testing">
    Passez en revue la stratégie de test nécessaire avant chaque release et son implémentation.
  </Card>
</Columns>


## Related topics

- [Construire une SPA avec Inertia.js](/fr/blog/inertia-introduction.md)
- [Gestion de la compatibilité de versions de package](/fr/advanced/package-versioning.md)
- [Laravel Package Skeleton — le template de démarrage pour packages officiels](/fr/blog/package-skeleton-introduction.md)
- [Présentation de Laravel Wayfinder](/fr/blog/wayfinder-introduction.md)
- [Gestion des erreurs](/fr/error-handling.md)