[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs:next\u002Fstability":3},{"versions":4,"version":17,"nav":20,"path":44,"page":96},[5,10,13],{"name":6,"label":7,"prefix":8,"channel":9},"0.2","0.2.0 (latest)","","latest",{"name":11,"label":12,"prefix":11,"channel":11},"next","next (main)",{"name":14,"label":15,"prefix":14,"channel":16},"0.1","0.1.0","old",{"name":11,"label":12,"prefix":11,"channel":11,"base":18,"ref":19},"\u002Fdocs\u002Fnext","main",[21,25,28,31,34,37,40,43,46,49,53,56,59,62,65,68,71,75,78,81,84,87,90,93],{"slug":22,"title":23,"group":24},"index","Overview","Guide",{"slug":26,"title":27,"group":24},"getting-started","Getting started",{"slug":29,"title":30,"group":24},"php","PHP API",{"slug":32,"title":33,"group":24},"laravel","Laravel",{"slug":35,"title":36,"group":24},"resources","Resources",{"slug":38,"title":39,"group":24},"deployment","Deployment",{"slug":41,"title":42,"group":24},"troubleshooting","Troubleshooting",{"slug":44,"title":45,"group":24},"stability","Stability and upgrades",{"slug":47,"title":48,"group":24},"ai-assistants","Docs for AI assistants",{"slug":50,"title":51,"group":52},"css","CSS reference","Reference",{"slug":54,"title":55,"group":52},"paged-media","Paged media",{"slug":57,"title":58,"group":52},"fonts","Fonts",{"slug":60,"title":61,"group":52},"extensions","Extensions",{"slug":63,"title":64,"group":52},"pdf","The PDF",{"slug":66,"title":67,"group":52},"cli","Command line",{"slug":69,"title":70,"group":52},"rust","Rust library",{"slug":72,"title":73,"group":74},"protocol","Worker protocol","Internals",{"slug":76,"title":77,"group":74},"releasing","Releasing",{"slug":79,"title":80,"group":74},"adr","Architecture decisions",{"slug":82,"title":83,"group":74,"parent":80},"adr\u002F0001-record-architecture-decisions","1. Record architecture decisions",{"slug":85,"title":86,"group":74,"parent":80},"adr\u002F0002-rust-and-fragmentation-in-layout","2. Rust core with fragmentation inside layout",{"slug":88,"title":89,"group":74,"parent":80},"adr\u002F0003-css-parsing-and-own-selector-matching","3. lightningcss for parsing, own selector matching and cascade",{"slug":91,"title":92,"group":74,"parent":80},"adr\u002F0004-extensions-only-where-css-has-no-way","4. Extensions only where CSS has no way",{"slug":94,"title":95,"group":74,"parent":80},"adr\u002F0005-public-api-and-deprecations","5. Public API, semantic versioning and deprecations",{"title":45,"seoTitle":97,"seoDescription":98,"html":99,"headings":100,"editUrl":120,"sourceUrl":121,"markdownUrl":122,"prev":123,"next":124},"Stability: versions, deprecations and upgrades","What the public API of Fagus is, what a release may change in the PDF it prints, how deprecations work and which PHP, Laravel and Rust versions it supports.","\u003Ch1 id=\"stability-and-upgrades\">Stability and upgrades\u003C\u002Fh1>\n\u003Cp>What you can rely on when you update Fagus, what a release may change and how you hear about\nwhat goes away. The reasons are in \u003Ca href=\"\u002Fdocs\u002Fnext\u002Fadr\u002F0005-public-api-and-deprecations\">ADR 5\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"versions\">Versions\u003Ca class=\"f-doc-anchor\" href=\"#versions\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>Fagus follows \u003Ca href=\"https:\u002F\u002Fsemver.org\">Semantic Versioning\u003C\u002Fa>. The PHP package, the binary, the Rust\ncrate and the worker protocol are released together, with one version number.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Before 1.0\u003C\u002Fstrong> (now: 0.2.0), a minor release such as 0.3.0 may change the API. The\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fnforst\u002Ffagus\u002Fblob\u002Fmain\u002FCHANGELOG.md\">changelog\u003C\u002Fa> lists every such change under\n\u003Cem>Changed\u003C\u002Fem> or \u003Cem>Removed\u003C\u002Fem>, with what to do instead. Patch releases such as 0.2.1 only fix bugs.\nRequire \u003Ccode>^0.2\u003C\u002Fcode> in Composer to get the patch releases and not the next minor one.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>From 1.0 on\u003C\u002Fstrong>, only a major release (2.0) breaks the API. Minor releases (1.1) add to it and\nmay deprecate parts of it; patch releases (1.0.1) fix bugs. \u003Ccode>^1.0\u003C\u002Fcode> is safe.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Security fixes may break what relied on the hole, in any release.\u003C\u002Fp>\n\u003Ch2 id=\"what-is-covered\">What is covered\u003Ca class=\"f-doc-anchor\" href=\"#what-is-covered\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>What these pages describe is the public API:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>PHP and Laravel:\u003C\u002Fstrong> the classes, methods, enums and exceptions of \u003Ca href=\"\u002Fdocs\u002Fnext\u002Fphp\">PHP API\u003C\u002Fa>, with the\nnames of their parameters; the facade, \u003Ccode>PendingPdf\u003C\u002Fcode>, the configuration keys and the commands of\n\u003Ca href=\"\u002Fdocs\u002Fnext\u002Flaravel\">Laravel\u003C\u002Fa>; the environment variables (\u003Ccode>FAGUS_BINARY\u003C\u002Fcode>, \u003Ccode>FAGUS_SYSTEM_FONTS\u003C\u002Fcode>,\n\u003Ccode>FAGUS_LOCALE\u003C\u002Fcode>, \u003Ccode>FAGUS_DOWNLOAD_URL\u003C\u002Fcode>, \u003Ccode>FAGUS_GITHUB_TOKEN\u003C\u002Fcode>). Not covered: anything marked\n\u003Ccode>@internal\u003C\u002Fcode> and the namespace \u003Ccode>Fagus\\Internal\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Rust:\u003C\u002Fstrong> the crate \u003Ccode>fagus\u003C\u002Fcode> with the types it exports and its features (\u003Ca href=\"\u002Fdocs\u002Fnext\u002Frust\">Rust library\u003C\u002Fa>).\nThe other crates of the repository are internal and change in any release.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Command line:\u003C\u002Fstrong> the commands, options, defaults and exit codes of \u003Ca href=\"\u002Fdocs\u002Fnext\u002Fcli\">Command line\u003C\u002Fa>, and\nthe format of diagnostics lines. Not the text of \u003Ccode>--help\u003C\u002Fcode>, of error messages or of \u003Ccode>--timings\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Worker protocol:\u003C\u002Fstrong> protocol 1 of \u003Ca href=\"\u002Fdocs\u002Fnext\u002Fprotocol\">Worker protocol\u003C\u002Fa>. Within a protocol number,\nnew fields and values may come; a client ignores fields it does not know. A new number comes\nonly with a major release.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>CSS:\u003C\u002Fstrong> the \u003Ca href=\"\u002Fdocs\u002Fnext\u002Fextensions\">extensions\u003C\u002Fa> with the \u003Ccode>-fagus-\u003C\u002Fcode> prefix.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Diagnostics:\u003C\u002Fstrong> the codes, such as \u003Ccode>css.invalid-value\u003C\u002Fcode>, and what they mean\n(\u003Ca href=\"\u002Fdocs\u002Fnext\u002Ftroubleshooting#read-diagnostics\">Troubleshooting\u003C\u002Fa>). Not their messages or severity.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>A minor release may add methods, optional parameters, enum cases, options, configuration keys,\nextensions and diagnostics codes. If you \u003Ccode>match\u003C\u002Fcode> over an enum of Fagus, give it a \u003Ccode>default\u003C\u002Fcode> arm.\u003C\u002Fp>\n\u003Ch2 id=\"what-may-change-in-any-release\">What may change in any release\u003Ca class=\"f-doc-anchor\" href=\"#what-may-change-in-any-release\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>The output. Fagus prints as Chrome does, and every release gets closer:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Layout, line and page breaks, and the page count may change, because Fagus follows Chrome or the\nspecifications more closely or fixes a bug, also where a document relied on the bug.\u003C\u002Fli>\n\u003Cli>CSS that was ignored may take effect.\u003C\u002Fli>\n\u003Cli>The bytes of the PDF change between releases, even with a fixed \u003Ccode>created()\u003C\u002Fcode> date. Within one\nrelease, the same document, fonts and date give the same bytes (\u003Ca href=\"\u002Fdocs\u002Fnext\u002Fpdf\">The PDF\u003C\u002Fa>).\u003C\u002Fli>\n\u003Cli>A document may get other diagnostics: fewer as Fagus learns CSS, more as it learns to check\nthings. Strict mode (\u003Ccode>strict()\u003C\u002Fcode>, \u003Ccode>--strict\u003C\u002Fcode>) can fail after an update on a document that passed\nbefore.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>If your tests compare PDFs byte by byte or as images, update the references with each release.\u003C\u002Fp>\n\u003Cp>What does not change in a minor release: the documented defaults (A4, tagged PDF, the built-in\nfont, no system fonts, American English for form controls), the PDF\u002FA levels, PDF\u002FUA and the\ninvoice profiles. What is safe never changes: no network access, no files outside the root, no\nscripts.\u003C\u002Fp>\n\u003Ch2 id=\"deprecations\">Deprecations\u003Ca class=\"f-doc-anchor\" href=\"#deprecations\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cp>Before something is removed in a major release, a minor release deprecates it and names what to\nuse instead. It keeps working until the next major release. You notice it:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>in PHP, as \u003Ccode>@deprecated\u003C\u002Fcode> in your IDE and static analysis, and at runtime as an\n\u003Ccode>E_USER_DEPRECATED\u003C\u002Fcode> notice that error handlers see (Laravel's \u003Ccode>deprecations\u003C\u002Fcode> log channel,\nPHPUnit), not on the screen;\u003C\u002Fli>\n\u003Cli>in Rust, as a compiler warning from \u003Ccode>#[deprecated]\u003C\u002Fcode>;\u003C\u002Fli>\n\u003Cli>on the command line, as a warning on standard error; the exit code stays the same;\u003C\u002Fli>\n\u003Cli>in CSS, as a \u003Ccode>css.deprecated\u003C\u002Fcode> diagnostic.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>The changelog lists deprecations under \u003Cem>Deprecated\u003C\u002Fem>. A major release comes with\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fnforst\u002Ffagus\u002Fblob\u002Fmain\u002FUPGRADING.md\">UPGRADING.md\u003C\u002Fa>, which lists every\nbreaking change and what to do; its section for 1.0 already collects what changed since 0.1.0.\u003C\u002Fp>\n\u003Ch2 id=\"supported-versions\">Supported versions\u003Ca class=\"f-doc-anchor\" href=\"#supported-versions\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Ctable class=\"f-doc-table f-stack-table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth>\u003C\u002Fth>\n\u003Cth>Now\u003C\u002Fth>\n\u003Cth>Raised\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>PHP\u003C\u002Ftd>\n\u003Ctd data-label=\"Now\">8.3 or newer\u003C\u002Ftd>\n\u003Ctd data-label=\"Raised\">In a minor release, once PHP stops security fixes for the version\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Laravel\u003C\u002Ftd>\n\u003Ctd data-label=\"Now\">13\u003C\u002Ftd>\n\u003Ctd data-label=\"Raised\">New majors in minor releases; an old one dropped once Laravel stops its security fixes\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Rust\u003C\u002Ftd>\n\u003Ctd data-label=\"Now\">1.97 or newer\u003C\u002Ftd>\n\u003Ctd data-label=\"Raised\">In a minor release, to a Rust release at least three months old, listed in the changelog\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Platforms\u003C\u002Ftd>\n\u003Ctd data-label=\"Now\">Linux (x64, arm64, glibc 2.17 or newer, musl), macOS (x64, arm64), Windows x64\u003C\u002Ftd>\n\u003Ctd data-label=\"Raised\">Dropped only in a major release\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003Cp>Composer keeps a project on an older PHP or Laravel at the last release that supports it.\nSecurity fixes go into the newest release (\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fnforst\u002Ffagus\u002Fblob\u002Fmain\u002FSECURITY.md\">security policy\u003C\u002Fa>).\u003C\u002Fp>\n\u003Ch2 id=\"updating\">Updating\u003Ca class=\"f-doc-anchor\" href=\"#updating\" aria-label=\"Link to this section\">#\u003C\u002Fa>\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>Read the changelog of every version between yours and the new one.\u003C\u002Fli>\n\u003Cli>Let Composer install the binary: the package works with the binary of its own release. A binary\nof another release through \u003Ccode>FAGUS_BINARY\u003C\u002Fcode> may ignore newer options (\u003Ca href=\"\u002Fdocs\u002Fnext\u002Fdeployment\">Deployment\u003C\u002Fa>).\u003C\u002Fli>\n\u003Cli>Run your templates with \u003Ccode>strict()\u003C\u002Fcode> or \u003Ccode>fagus render --strict\u003C\u002Fcode> in CI to see new diagnostics.\u003C\u002Fli>\n\u003C\u002Ful>\n",[101,105,108,111,114,117],{"id":102,"text":103,"level":104},"versions","Versions",2,{"id":106,"text":107,"level":104},"what-is-covered","What is covered",{"id":109,"text":110,"level":104},"what-may-change-in-any-release","What may change in any release",{"id":112,"text":113,"level":104},"deprecations","Deprecations",{"id":115,"text":116,"level":104},"supported-versions","Supported versions",{"id":118,"text":119,"level":104},"updating","Updating","https:\u002F\u002Fgithub.com\u002Fnforst\u002Ffagus\u002Fedit\u002Fmain\u002Fdocs\u002Fstability.md","https:\u002F\u002Fgithub.com\u002Fnforst\u002Ffagus\u002Fblob\u002Fmain\u002Fdocs\u002Fstability.md","\u002Fdocs\u002Fnext\u002Fstability.md",{"slug":41,"title":42},{"slug":47,"title":48}]