Guía de compatibilidad hacia atrás

Asegurar que puedas actualizar tus aplicaciones fácilmente es importante para nosotros. Por ello sólo rompemos la compatibilidad en las liberaciones de versiones major. Puedes familiarizarte con el versionado semántico, el cual utilizamos en todos los proyectos de CakePHP. Pero resumiendo, el versionado semántico significa que sólo las liberaciones de versiones major (tales como 2.0, 3.0, 4.0) pueden romper la compatibilidad hacia atrás. Las liberaciones minor (tales como 2.1, 3.1, 3.2) pueden introducir nuevas funcionalidades pero no pueden romper la compatibilidad. Los lanzamientos de correcciones de errores (tales como 3.0.1) no añaden nuevas funcionaliades, sólo correcciones de errores o mejoras de rendimiento.

Nota

CakePHP empezó a seguir el versionado semántico a partir de la 2.0.0. Estas reglas no se aplican en las versiones 1.x.

Para aclarar que cambios puedes esperar de cada nivel de lanzamiento tenemos más información detallada para desarrolladores que utilizan CakePHP y que trabajan en él que ayudan a aclarar que puede hacerse en liberaciones minor. Las liberaciones major pueden tener tantas rupturas de compatibilidad como sean necesarias.

Guías de migración

Para cada liberación major y minor el equipo de CakePHP facilitará una guía de migración. Estas guías explican las nuevas funcionaliades y cualquier ruptura de compatibilidad que haya en cada lanzamiento. Pueden encontrarse en la sección Apéndices del cookbook.

Usar CakePHP

Si estás desarrollando tu aplicación con CakePHP las siguientes pautas explican la estabilidad que puedes esperar.

Interfaces

Con excepción de las liberaciones major, las interfaces que provee CakePHP no tendrán ningún cambio en los métodos existentes. Podrán añadirse nuevos métodos pero no habrá cambios en los ya existentes.

Clases

Las clases que proporciona CakePHP pueden estar construidas y tener sus métodos y propiedades públicos usados por el código de la aplicación y, a excepción de las liberaciones major, la compatibilidad hacia atrás está garantizada.

Nota

Algunas clases en CakePHP están marcadas con la etiqueta API doc @internal. Estas clases no son estables y no garantizan la compatibilidad hacia atrás.

En liberaciones minor pueden añadirse nuevos métodos a las clases y a los ya existentes nuevos argumentos. Cualquier argumento nuevo tendrá un valor por defecto, pero si sobreescribes métodos con una firma diferente puedes encontrar fatal errors. Los métodos con nuevos argumentos estarán documentados en las guías de migración..

La siguiente tabla esboza varios casos de uso y que compatibilidad puedes esperar de CakePHP:

Si tu… ¿Compatible hacia atrás?
Tipificas contra la clase Si
Creas una nueva instancia Si
Extiendes la clase Si
Accedes a una propiedad pública Si
Llamas un método público Si
Extiendes una clase y…
Sobrescribes una propiedad pública Si
Accedes a una propiedad protegida No [1]
Sobreescribes una propiedad protegida No [1]
Sobreescribes un método protegido No [1]
Llamas a un método protegido No [1]
Añades una propiedad pública No
Añades un método público No
Añades un argumento a un método sobreescrito No [1]
Añades un valor por defecto a un argumento de método existente Si

Trabajando en CakePHP

Si estás ayudando a que CakePHP sea aún mejor, por favor, ten en mente las siguientes pautas cuando añadas/cambies funcionalidades:

En una liberación minor puedes:

En una liberación minor puedes…
Clases
Eliminar una clase No
Eliminar una interfaz No
Eliminar un trait No
Hacer final No
Hacer abstract No
Cambiar el nombre Si [2]
Propiedades
Añadir una propiedad pública Si
Eliminar una propiedad pública No
Añadir una propiedad protegida Si
Eliminar una propiedad protegida Si [3]
Métodos
Añadir un método público Si
Eliminar un método público No
Añadir un método protegido Si
Mover a la clase padre Si
Eliminar un método protegido Si [3]
Reducir visibilidad No
Cambiar nombre del método Si [2]
Añadir un argumento nuevo con valor por defecto Si
Añadir un nuevo argumento obligatorio a un método existente No
Eliminar un valor por defecto de un argumento existente No
[1](1, 2, 3, 4, 5) Tu código puede romperse en lanzamientos minor. Comprueba la guía de migración para más detalles.
[2](1, 2) Puedes cambiar el nombre de una clase/método siempre y cuando el antiguo nombre se mantenga disponible. Esto es evitado generalmente a menos que el cambio de nombre sea significativamente beneficioso.
[3](1, 2) Evitarlo cuando sea posible. Cualquier borrado tendrá que ser documentado en la guía de migración.