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

<Info>
  Questa pagina è la sorella di [Sviluppo di pacchetti Laravel](/it/advanced/package-development). Per la strategia di compatibilità con Laravel/PHP consulta [Gestire la compatibilità tra versioni dei pacchetti](/it/advanced/package-versioning).
</Info>

## 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](https://keepachangelog.com/en/1.1.0/) 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]`

```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>
  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.
</Tip>

## Semantic Versioning (SemVer)

Il [Semantic Versioning](https://semver.org/spec/v2.0.0.html) 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](https://laravel.com/docs/13.x/upgrade). Le release più recenti sono su [laravel/framework releases](https://github.com/laravel/framework/releases). Se ci sono breaking change sulle API che il pacchetto usa, devi riprogettare la policy di compatibilità.

<Warning>
  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.
</Warning>

## Tag Git e GitHub Releases

Prima crei il tag Git e lo pushi su origin.

```bash theme={null}
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.

<Steps>
  <Step title="Fai merge su main del commit di release">
    Fai merge su `main` con tutti i test verdi.
  </Step>

  <Step title="Crea e pusha il tag Git">
    Crea un tag nella forma `vX.Y.Z` e pushalo su `origin`.
  </Step>

  <Step title="Pubblica la GitHub Release">
    Come titolo usa il nome del tag; come corpo la sezione corrispondente del CHANGELOG.
  </Step>
</Steps>

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

```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>
  Impostando `needs: test` sul job `release` puoi bloccare la pubblicazione se i test falliscono. Mantieni sempre questo gate, sia con release manuali che automatiche.
</Info>

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

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

```markdown theme={null}
## 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

<Columns cols={3}>
  <Card title="Sviluppo di pacchetti Laravel" icon="box" href="/it/advanced/package-development">
    Rivedi le basi di implementazione centrate sui service provider.
  </Card>

  <Card title="Gestire la compatibilità tra versioni dei pacchetti" icon="git-branch" href="/it/advanced/package-versioning">
    Riorganizza compatibilità Laravel/PHP e criteri di uso di SemVer.
  </Card>

  <Card title="Testare pacchetti Laravel con Orchestra Testbench" icon="flask-conical" href="/it/advanced/package-testing">
    Verifica le strategie di test e l'implementazione necessarie prima di ogni release.
  </Card>
</Columns>


## Related topics

- [Gestire la compatibilità tra versioni dei pacchetti](/it/advanced/package-versioning.md)
- [Laravel Package Skeleton — template starter per pacchetti ufficiali](/it/blog/package-skeleton-introduction.md)
- [Testare pacchetti Laravel con Orchestra Testbench](/it/advanced/package-testing.md)
- [Presentazione di Laravel Wayfinder](/it/blog/wayfinder-introduction.md)
- [Come creare uno starter kit per Laravel](/it/advanced/starter-kit-creation.md)