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.
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 unifica la estructura de categorías dentro del equipo.
Coloca enlaces de comparación al final para poder seguir las diferencias.
Acumula los cambios aún no publicados en ## [Unreleased].
# CHANGELOGAll 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
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.
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 para conocer los cambios de Laravel. La situación de las releases más recientes puede consultarse en laravel/framework releases. Si algún cambio rompe una API que utiliza tu paquete, replantea tu política de compatibilidad.
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.
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.
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.
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.
<?phpnamespace 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; }}
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».
