Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
79 lines (60 loc) · 4.33 KB

CONTRIBUTING.md

File metadata and controls

79 lines (60 loc) · 4.33 KB

Maintainers guide

Release process

  1. Changelog. Add a new section to the top of CHANGES.md with the output from composer changelog.

    Edit your new section by following the Keep a changelog conventions, where by bullet points are under one of the "Added", "Changed", "Fixed", "Deprecated", or "Removed" labels.

    Review each point and make sure it is phrased in a way that explains the impact on end-users of the library. If the change does not affect the public API or CSS output, remove the bullet point.

  2. Version bump. Update /lib/Less/Version.php and set version to the version that you're about to release. Also increase cache_version to increment the last number.

  3. Commit. Stage and commit your changes with the message Tag vX.Y.Z, and then push the commit for review.

  4. Tag. After the above release commit is merged, checkout the master branch and pull down the latest changes. Then create a vX.Y.Z tag and push the tag.

    Remember to, after the commit is merged, first checkout the master branch and pull down the latest changes. This is to make sure you have the merged version and not the draft commit that you pushed for review.

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
      • ImportVisitor applies these steps to each Import node:
        • ImportVisitor#processImportNode
        • Import#evalForImport
      • ImportVisitor ends with ImporVisitor#tryRun loop (async, after last call to ImportVisitor#onImported.
  • 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 Less_ImportVisitor
      • Less_ImportVisitor applies these steps to each Import node:
        • ImportVisitor->processImportNode
        • Less_Tree_Import->compileForImport
      • ImportVisitor ends with ImporVisitor#tryRun loop (all sync, no async needed).
    • 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.