Documentación · Referencia · El formato de un proyecto
12. Reglas que no se rompen
Las reglas del formato que no cambian dentro de una versión mayor.
Versión 0.16
- Un editor no guarda nada que el motor no pueda leer desde la carpeta.
- La orden de consola y cualquier programa que incruste el motor usan la misma API; la orden es una envoltura fina.
- Un proyecto exportado en zip compila en cualquier máquina con PHP y da el
mismo HTML con la misma versión del motor y de sus dependencias, salvo lo
que una plantilla elija al azar con
random()o saque de la fecha del momento (§7.3), y salvo qué páginas salen, que depende del momento en que se compila (publicarypublicarEnSuFecha, §4). Entre versiones del motor no se promete el mismo HTML byte a byte: Twig 3, CommonMark 2, Symfony YAML 8 y dompdf 3, que Composer deja actualizar dentro de su versión mayor, deciden partes del resultado (el escapado, las listas, las tablas y las notas al pie, cómo se leen el front matter, las fechas y los números, los bytes de un PDF), y lo que cambie se anota en las notas de la versión. - El motor no ejecuta código propio del sitio (PHP que venga del proyecto), y no lo hará dentro de una versión mayor del formato (§2): es una promesa, como la de la regla 5.
- Dentro de una versión mayor del formato (§2), el contrato solo crece: un
campo, una función, un filtro, un tipo de campo del esquema o una opción
nuevos no cambian lo que ya significaba un proyecto escrito. Quitar algo
o cambiar su significado es una versión mayor. Lo que va a dejar de valer
se avisa durante, al menos, una versión menor antes de quitarse. Tiene una
excepción, la de los nombres: un campo reservado nuevo (§4), una clave nueva
de
sitio.yml(§2), un nombre nuevo que el motor escriba enpagina(§7.2) o una variable nueva de un atajo (§8.1) puede tapar un campo, una clave o un atributo propios que un sitio ya tuviera con ese nombre. Por eso se anuncia en una versión menor, y el motor que lo añade avisa a los sitios que ya lo usan como propio. - La biblioteca PHP y la orden de consola prometen lo que dice
biblioteca.md, con la misma regla: lo que no está allí puede cambiar en cualquier versión. - Los nombres siguen una regla, y los nuevos la cumplen. Los campos, las claves
de
sitio.ymly las variables que ve una plantilla se escriben en español, en una palabra o en camelCase, sin guiones (porPagina,imagenAlt,publicarEnSuFecha); los atributos de HTML conservan el suyo (sizes,srcset,alt,href,rel). Las funciones y los filtros de Twig siguen la convención de Twig: una palabra o con guion bajo (css_fichero, comonumber_formatojson_encode). Los nombres que ya hay no se renombran (regla 5), pero pueden recibir un alias. Las palabras que se repiten con otro sentido según dónde estén (orden,grupo,carpeta,fichero,excluir) están en una tabla deesquema.md.