Hi Bertrand, for the added instructions this may be good enough. But in some cases instructions have been extended, e.g. 1) intermediate path support for user creation (https://issues.apache.org/jira/browse/SLING-7226) 2) forced intermediate path support for user creation (https://issues.apache.org/jira/browse/SLING-9857)
Both are currently not documented at all. I would appreciate a more formal approach. The more features you add to the language the more complicated it gets, especially with instructions having optional arguments/directives For me it would be good to have a list of instructions which contains the following data per instruction: - The syntax of the instruction (clearly indicating which directives are required vs. which are optional, e.g. "path" directive for "create user" is optional. - A short description what it does. - Related JIRA ticket (multiple ones possible) - Repoinit language version, repoinit parser version and jcr.repoinit version WDYT? Konrad > On 12. Feb 2021, at 14:28, Bertrand Delacretaz <[email protected]> wrote: > > Hi Konrad, > > On Mon, Feb 8, 2021 at 4:56 PM Konrad Windszus <[email protected]> wrote: >> ...what is IMHO missing is: >> - Documentation of language version with each added feature listed... > > The examples at [1] include comments such as > > # Setting repository level ACL require > # o.a.s.repoinit.parser 1.2.0 and > # o.a.s.jcr.repoinit 1.1.6 > > but if you think we need something more formal we might use the history of > the test scripts [2] to generate more precise documentation? By correlating > the history of statements appearing in those scripts with the module > version and generating a Markdown document out of that. > >> - Required minimum language version statement... > > Recent versions of the parser module define an OSGi capability for the > language version, like > > Provide-Capability: > org.apache.sling.repoinit.language;version:Version="8.2" > > (which the jcr-repoinit module specifies as a requirement to avoid both > modules being out of sync) > > So we might add a statement in the language like > > REQUIRE language.version 8.2 > > That does nothing but fails if the current parser is a lower version? It > would only start working from now on obviously, unless we put this > statement in a comment so that older versions of the parser accept it. > > I think this would work fine if multiple repoinit fragments are aggregated, > if any of them requires a version that's not provided the whole execution > would fail which is IMO what we want. > > -Bertrand > > [1] > https://sling.apache.org/documentation/bundles/repository-initialization.html > [2] > https://github.com/apache/sling-org-apache-sling-repoinit-parser/tree/master/src/test/resources/testcases
