we make in our Java code a distinction between our internal code that it’s ok to break and change, and our exposed API that is only unstable when it’s new and that we should not break or only with a vote afterwards.
For our velocity code however, we don’t have such distinction, so de facto any macros that we write in a velocity template bundled in XWiki Standard becomes an API.
This is making the work of improving XWiki Standard a bit difficult as we’re not supposed to break those, and we’re supposed to keep maintaining them. So for helping us on the long run, I propose that we start having a distinction between our velocity macros that are exposed as APIs and our velocity macros that are only supposed to be internal.
For making that distinction, we don’t have much choice in velocity other than having a specific naming scheme, and proper documentation.
The proposal here is to prefix every internal macro name with
_ to make clear that it’s a technical one and it’s not supposed to be used externally. Then for those macro it would be ok to break them.
So there’s 2 things for which we need an agreement:
- Are you ok with the principles of making such a distinction between internal velocity macros and API velocity macros?
- Are you ok to use
_as naming prefix for the internal macros?
If we agree on this, I then propose the following plan to apply this rule:
- We document this as a new best practice in dev.xwiki.org
- We create a task for renaming the internal velocity macros we have in XS, we create a PR with the changes, and we open a vote before merging the PR to ensure everyone is ok with the move to internal of the selected macros. Once merged the change will be documented in the migration notes of the RN. IMO this should be done only in 16.x
- In the future, we work on tooling for also having unstable annotation on our API velocity macros and to detect missing doc on them