> ## 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 y gestión de releases de paquetes

> Explica prácticas de gestión de releases necesarias para el mantenimiento a largo plazo de paquetes Laravel, desde el historial de cambios hasta la automatización de GitHub Releases.

Si vas a mantener un paquete Laravel durante mucho tiempo, prepara desde el principio el historial de cambios y el procedimiento de release. Sistematizar la gestión de releases evita olvidos al anunciar cambios rompedores y que la tarea dependa de una única persona.

<Info>
  Esta página es hermana de [Desarrollo de paquetes Laravel](/es/advanced/package-development). Para la estrategia de compatibilidad con Laravel/PHP, consulta [Gestión de la compatibilidad de versiones de paquetes](/es/advanced/package-versioning).
</Info>

## Cómo escribir el CHANGELOG.md

El CHANGELOG es la fuente primaria donde los usuarios consultan «qué cambió, cuándo y en qué versión». Adoptar el formato de [Keep a Changelog](https://keepachangelog.com/es/1.1.0/) unifica la estructura de categorías dentro del equipo.

### Reglas básicas

* Titula cada versión con el formato `## [x.y.z] - YYYY-MM-DD`.
* Usa `Added / Changed / Deprecated / Removed / Fixed / Security`.
* Coloca enlaces de comparación al final para poder seguir las diferencias.
* Acumula los cambios aún no publicados en `## [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>
  Usa como notas de la release el fragmento correspondiente del CHANGELOG. Con una única fuente de verdad para el historial evitas divergencias entre README, GitHub Releases y anuncios en redes sociales.
</Tip>

## Versionado semántico (SemVer)

En [Semantic Versioning](https://semver.org/spec/v2.0.0.html), `MAJOR.MINOR.PATCH` se usa con estos criterios:

* **MAJOR**: cambios que rompen la compatibilidad hacia atrás (Breaking changes).
* **MINOR**: adiciones de funcionalidad manteniendo la compatibilidad hacia atrás.
* **PATCH**: correcciones de bugs manteniendo la compatibilidad hacia atrás.

### Ejemplos de decisión en un paquete Laravel

La compatibilidad con Laravel 13 se trata de forma distinta según el cambio.

| Cambio                                                       | Versión recomendada |
| ------------------------------------------------------------ | ------------------- |
| Mantener el soporte a Laravel 12 y añadir `^13.0`.           | MINOR               |
| Retirar soporte a Laravel 11/12 y quedarte solo con `^13.0`. | MAJOR               |
| Corrección de bug que solo ocurre en Laravel 13.             | PATCH               |

Consulta siempre la [guía de actualización](https://laravel.com/docs/13.x/upgrade) para conocer los cambios de Laravel. La situación de las releases más recientes puede consultarse en [laravel/framework releases](https://github.com/laravel/framework/releases). Si algún cambio rompe una API que utiliza tu paquete, replantea tu política de compatibilidad.

<Warning>
  Subir el requisito mínimo de PHP o eliminar una API pública también es un Breaking change desde el punto de vista del usuario. Aunque coincida con la migración a una nueva Laravel major, trátalo como un release MAJOR.
</Warning>

## Tags de Git y GitHub Releases

Primero crea el tag de Git y hazle push a origin.

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

Después, en la pantalla de creación de Release de GitHub selecciona el tag `v2.1.0` y publícalo. Pega en el cuerpo la sección `## [2.1.0]` del CHANGELOG.

<Steps>
  <Step title="Mergea a main el commit objetivo del release">
    Con todos los tests en verde, mergea en `main`.
  </Step>

  <Step title="Crea y publica el tag de Git">
    Crea un tag con el formato `vX.Y.Z` y hazle push a `origin`.
  </Step>

  <Step title="Publica el GitHub Release">
    Título: el nombre del tag; cuerpo: la sección correspondiente del CHANGELOG.
  </Step>
</Steps>

## Releases automatizados con GitHub Actions

Si usas `push: tags:` como disparador, la creación de un tag publica automáticamente el GitHub Release. Con `softprops/action-gh-release` puedes reutilizar directamente el contenido de `CHANGELOG.md` como cuerpo.

```mermaid theme={null}
flowchart LR
    A["Merge a main"] --> B["Crear tag<br>vX.Y.Z"]
    B --> C["GitHub Actions<br>on push tags"]
    C --> D["Ejecutar job de tests"]
    D --> E["Publicar 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>
  Con `needs: test` en el job `release`, si los tests fallan, la publicación se detiene. Mantén siempre esa protección, tanto para releases manuales como automáticos.
</Info>

## Cómo gestionar los Breaking changes

Diseña los Breaking changes para permitir una migración por fases. Marca primero como deprecado y elimina en el siguiente MAJOR: reducirás el coste de migración de tus usuarios.

### 1. Señala la deprecación en el código

```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 guía de migración

En `UPGRADE.md` o en una página dedicada, describe paso a paso los cambios que esperas que hagan tus usuarios.

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

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

### 3. Deja notas de migración entre versiones MAJOR

Al subir de MAJOR, enlaza mutuamente la sección `Removed` del CHANGELOG con la guía de migración. Así, los usuarios pueden ver de un vistazo «qué se eliminó» y «cómo arreglarlo».

## Páginas relacionadas

<Columns cols={3}>
  <Card title="Desarrollo de paquetes Laravel" icon="box" href="/es/advanced/package-development">
    Repasa los fundamentos de implementación centrados en los service providers.
  </Card>

  <Card title="Gestión de la compatibilidad de versiones de paquetes" icon="git-branch" href="/es/advanced/package-versioning">
    Organiza los criterios de compatibilidad Laravel/PHP y el uso de SemVer.
  </Card>

  <Card title="Probar paquetes Laravel con Orchestra Testbench" icon="flask-conical" href="/es/advanced/package-testing">
    Revisa la estrategia y la implementación de pruebas necesarias antes del release.
  </Card>
</Columns>


## Related topics

- [Gestión de la compatibilidad de versiones de paquetes](/es/advanced/package-versioning.md)
- [Laravel Package Skeleton — Plantilla oficial para paquetes](/es/blog/package-skeleton-introduction.md)
- [Análisis estático de paquetes (PHPStan / Larastan)](/es/advanced/package-static-analysis.md)
- [Cómo crear un starter kit de Laravel](/es/advanced/starter-kit-creation.md)
- [Presentación de Laravel Wayfinder](/es/blog/wayfinder-introduction.md)