From 4c41bb193b70d312d22d1c30f75723bdf23d5cae Mon Sep 17 00:00:00 2001 From: Timo Tijhof Date: Mon, 19 Feb 2024 23:47:17 +0000 Subject: [PATCH] docs: Write "Overview" and "Compatibility" in CONTRIBUTING.md Also fix a broken link in README.md. Bug: T353133 Change-Id: Id6dbbbd916993d7f71fc4fe34766559982bb3847 --- CONTRIBUTING.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 ++-- 2 files changed, 54 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..b1f6f946 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Maintainers guide + +## Internal overview + +This is an overview of the high-level steps during the transformation +from Less to CSS, and how they compare between Less.js and Less.php. + +Less.js: + +* `less.render(input, { paths: … })` + * `Parser.parse` normalizes input + * `Parser.parse` parses input into rules via `parsers.primary` + * `Parser.parse` creates the "root" ruleset object + * `Parser.parse` applies ImportVisitor +* `less.render` callback + * `ParseTree.prototype.toCSS` + * `transformTree` applies pre-visitors, compiles all rules, and applies post-visitors. + * `ParseTree.prototype.toCSS` runs toCSS transform on the "root" ruleset. +* CSS result ready! + +Less.php + +* `Less_Parser->parseFile` + * `Less_Parser->_parse` + * `Less_Parser->GetRules` normalizes input (via `Less_Parser->SetInput`) + * `Less_Parser->GetRules` parses input into rules via `Less_Parser->parsePrimary` +* `Less_Parser->getCss` + * `Less_Parser->getCss` creates the "root" ruleset object + * `Less_Parser->getCss` applies pre-visitors, compiles all rules, and applies post-visitors. + * `Less_Parser->getCss` runs toCSS transform on the "root" ruleset. +* CSS result ready! + +## Compatibility + +The `wikimedia/less.php` package inherits a long history of loosely compatible +and interchangable Less compilers written in PHP. + +Starting with less.php v3.2.1 (released in 2023), the public API is more clearly +documented, and internal code is now consistently marked `@private`. + +The public API includes the `Less_Parser` class and several of its public methods. +For legacy reasons, some of its internal methods remain public. Maintainers must +take care to search the following downstream applications when changing or +removing public methods. If a method has one or more references in the below +codebases, treat it as a breaking change and document a migration path in the +commit message (and later in CHANGES.md), even if the method was undocumented +or feels like it is for internal use only. + +* [MediaWiki (source code)](https://codesearch.wmcloud.org/core/?q=Less_Parser&files=php%24) +* [Matomo (source code)](https://github.com/matomo-org/matomo/blob/5.0.2/core/AssetManager/UIAssetMerger/StylesheetUIAssetMerger.php) +* [Adobe Magento (source code)](https://github.com/magento/magento2/blob/2.4.6/lib/internal/Magento/Framework/Css/PreProcessor/Adapter/Less/Processor.php) +* [Shopware 5 (source code)](https://github.com/shopware5/shopware/blob/5.7/engine/Shopware/Components/Theme/LessCompiler/Oyejorge.php) diff --git a/README.md b/README.md index 3d76ec7c..a88aff14 100644 --- a/README.md +++ b/README.md @@ -43,8 +43,8 @@ _See also [SECURITY](./SECURITY.md)._ ## Who uses Less.php? * **[Wikipedia](https://en.wikipedia.org/wiki/MediaWiki)** and the MediaWiki platform ([docs](https://www.mediawiki.org/wiki/ResourceLoader/Architecture#Resource:_Styles)). -* **[Matomo](https://en.wikipedia.org/wiki/Matomo_(software))** ([docs](https://devdocs.magento.com/guides/v2.4/frontend-dev-guide/css-topics/custom_preprocess.html)). -* **[Magento](https://en.wikipedia.org/wiki/Magento)** as part of Adobe Commerce ([docs](https://developer.matomo.org/guides/asset-pipeline#vanilla-javascript-css-and-less-files)). +* **[Matomo](https://en.wikipedia.org/wiki/Matomo_(software))** ([docs](https://developer.matomo.org/guides/asset-pipeline#vanilla-javascript-css-and-less-files)). +* **[Magento](https://en.wikipedia.org/wiki/Magento)** as part of Adobe Commerce ([docs](https://developer.adobe.com/commerce/frontend-core/guide/css/preprocess/)). * **[Icinga](https://en.wikipedia.org/wiki/Icinga)** in Icinga Web ([docs](https://github.com/Icinga/icingaweb2)). * **[Shopware](https://de.wikipedia.org/wiki/Shopware)** ([docs](https://developers.shopware.com/designers-guide/less/)).