CHANGELOG et gestion des releases de packages

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.

Cette page est la sœur de Développement de packages Laravel. Pour la stratégie de compatibilité Laravel/PHP, consultez Gestion de la compatibilité de versions de package.

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

# 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

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.

Versionnement sémantique (SemVer)

Le Semantic Versioning 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. L’état de la dernière release est consultable sur laravel/framework releases. Si les API utilisées par votre package subissent un changement cassant, votre politique de compatibilité doit être revue.

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.

Tags Git et GitHub Releases

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

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.

Fusionner le commit cible dans main

Fusionnez sur main alors que tous les tests sont au vert.

Créer et pousser le tag Git

Créez un tag au format vX.Y.Z et poussez-le vers origin.

Publier la GitHub Release

Utilisez le nom du tag comme titre et la section correspondante du CHANGELOG comme corps.

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.

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

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.

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

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.

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

Développement de packages Laravel

Passez en revue les fondations de l’implémentation autour du service provider.

Gestion de la compatibilité de versions de package

Structurez vos critères de décision autour de la compatibilité Laravel/PHP et l’usage de SemVer.

Tester des packages Laravel avec Orchestra Testbench

Passez en revue la stratégie de test nécessaire avant chaque release et son implémentation.

​Rédiger le CHANGELOG.md

​Règles de base

​Versionnement sémantique (SemVer)

​Exemples de décision pour un package Laravel

​Tags Git et GitHub Releases

​Release automatique via GitHub Actions

​Gérer les Breaking changes

​1. Signaler la dépréciation dans le code

​2. Documenter le guide de migration

​3. Laisser des notes de migration entre versions majeures

​Pages associées

Développement de packages Laravel

Gestion de la compatibilité de versions de package

Tester des packages Laravel avec Orchestra Testbench

Rédiger le CHANGELOG.md

Règles de base

Versionnement sémantique (SemVer)

Exemples de décision pour un package Laravel

Tags Git et GitHub Releases

Release automatique via GitHub Actions

Gérer les Breaking changes

1. Signaler la dépréciation dans le code

2. Documenter le guide de migration

3. Laisser des notes de migration entre versions majeures

Pages associées