CHANGELOG e release management dei pacchetti

Dalla gestione della cronologia delle modifiche di un pacchetto Laravel all’automazione delle release su GitHub, le pratiche di release management necessarie per la manutenzione a lungo termine.

Se hai intenzione di manutenere a lungo un pacchetto Laravel, prepara subito la cronologia delle modifiche e la procedura di release. Sistemare il release management previene omissioni nella comunicazione dei breaking change e la personalizzazione eccessiva delle attività di rilascio.

Questa pagina è la sorella di Sviluppo di pacchetti Laravel. Per la strategia di compatibilità con Laravel/PHP consulta Gestire la compatibilità tra versioni dei pacchetti.

​

Come scrivere il CHANGELOG.md

Il CHANGELOG è la fonte primaria dove gli utenti leggono “cosa, quando, in quale versione è cambiato”. Adottando il formato Keep a Changelog uniformi la struttura delle categorie in tutto il team.

​

Regole di base

• Titola le versioni nella forma ## [x.y.z] - YYYY-MM-DD
• Usa le categorie Added / Changed / Deprecated / Removed / Fixed / Security
• Metti in fondo i link di confronto per poter seguire le differenze
• Le modifiche non ancora rilasciate finiscono in ## [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

Come release note usa direttamente la sezione corrispondente del CHANGELOG. Concentrando la fonte informativa in un solo luogo, i contenuti restano allineati tra README, GitHub Releases e annunci sui social.

​

Semantic Versioning (SemVer)

Il Semantic Versioning usa MAJOR.MINOR.PATCH con questi criteri.

• MAJOR: cambiamenti che rompono la retrocompatibilità (breaking change)
• MINOR: aggiunte di funzionalità retrocompatibili
• PATCH: fix retrocompatibili

​

Esempi di scelta per un pacchetto Laravel

Il supporto a Laravel 13 si tratta diversamente in base al contenuto della modifica.

Cambiamento	Versione consigliata
Mantieni il supporto a Laravel 12 aggiungendo ^13.0	MINOR
Dismetti il supporto a Laravel 11/12 e lasci solo ^13.0	MAJOR
Fix di un bug che si presenta solo su Laravel 13	PATCH

Verifica sempre i contenuti dell’upgrade di Laravel nella Upgrade Guide. Le release più recenti sono su laravel/framework releases. Se ci sono breaking change sulle API che il pacchetto usa, devi riprogettare la policy di compatibilità.

Innalzare il requisito minimo di PHP o rimuovere API pubbliche sono, dal punto di vista degli utenti, breaking change. Anche se coincidono con l’adattamento a un nuovo major di Laravel, trattali come release MAJOR.

​

Tag Git e GitHub Releases

Prima crei il tag Git e lo pushi su origin.

git tag v2.1.0
git push origin v2.1.0

Poi, dalla schermata di creazione release di GitHub, selezioni il tag v2.1.0 e lo pubblichi. Nel corpo incolli la sezione ## [2.1.0] del CHANGELOG.

1. Fai merge su main del commit di release

   Fai merge su main con tutti i test verdi.

2. Crea e pusha il tag Git

   Crea un tag nella forma vX.Y.Z e pushalo su origin.

3. Pubblica la GitHub Release

   Come titolo usa il nome del tag; come corpo la sezione corrispondente del CHANGELOG.

​

Release automatiche con GitHub Actions

Usando push: tags: come trigger puoi pubblicare automaticamente le GitHub Releases al momento della creazione del tag. Con softprops/action-gh-release puoi riutilizzare direttamente i contenuti di CHANGELOG.md.

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

Impostando needs: test sul job release puoi bloccare la pubblicazione se i test falliscono. Mantieni sempre questo gate, sia con release manuali che automatiche.

​

Come gestire i breaking change

Progetta i breaking change perché possano essere adottati in modo graduale. Prima deprechi, poi rimuovi nella MAJOR successiva: così riduci il costo di migrazione per gli utenti.

​

1. Segnala la deprecazione a livello di codice

<?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. Documenta la guida di migrazione

In UPGRADE.md o in una pagina dedicata metti in sequenza le modifiche che gli utenti devono applicare.

## Upgrading from v2 to v3

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

​

3. Lascia note di migrazione tra le versioni major

Quando fai un salto MAJOR, collega tra loro Removed nel CHANGELOG e la guida di migrazione. L’utente vede in un colpo “cosa è stato rimosso” e “come sistemarlo”.

​

Pagine correlate

Sviluppo di pacchetti Laravel

Rivedi le basi di implementazione centrate sui service provider.

Gestire la compatibilità tra versioni dei pacchetti

Riorganizza compatibilità Laravel/PHP e criteri di uso di SemVer.

Testare pacchetti Laravel con Orchestra Testbench

Verifica le strategie di test e l’implementazione necessarie prima di ogni release.