Modules naming and organization

Development
1

Hello all,

I’d like to discuss the naming and organization of modules in xwiki-platform.

To the best of my knowledge, we don’t have centralized documentation to explain how modules must be named and where to place them in the hierarchy.
Slightly related, we have a few discussions on the archived mailing list about the repository location of modules (Re: [xwiki-devs] [Proposal] XWiki Core, [xwiki-devs] [VOTE] XWiki Core - Take 3).

For some context, the discussion comes from my current work to integrate npm packages in xwiki-platform.
For this work, I’d like to be able to clearly distinguish between:

  • packages that need to be published on npm registries
  • packages that need to be published on maven repositories as webjars

So first, the general rule is that modules are grouped by business domain. In other words, we group together modules that are about the same topic.

Meaning that the hierarchy is:

notifications
|- api
|- default
|- ui
chart
|- api
|- macro
|- rendered

and not:

api
|-notifications
|-chart
default
|-notifications
ui
|-notifications
[...]

Note that a domain can have subdomains. For instance, xwiki-platform-captcha and xwiki-platform-captcha-jcaptcha.

For a given business domain, developers are free to use arbitrary suffixes. But there is a set of standard ones that we need to see used uniformly. See below a non-exhaustive list of common suffixes.

  • api - the extension APIs
  • default - the default APIs implementations (optional; the implementation can be in an internal package in api if it is not causing circular dependency issues)
  • webjar - packages client-side artifacts (most commonly CSS, Less and JavaScript files).
  • ui - the wiki pages providing the UI elements for the extension
  • renderer - the parsing and serializing components supporting the extension

From this, hopefully consensual, base. I’d like to introduce a new npm specific type:
node - for npm packages that are meant to be published on npm registries to be reused by external projects (e.g., xwiki-platform-notifications-node could contain client-side APIs used by other client-side code to manipulate notifications, be it inside XWiki, or on external projects such as Cristal).
A node module can contain several npm packages, for instance,

  • @xwiki/platform-notifications-api for the client-side APIs
  • @xwiki/platform-notifications-ui for reusable client-side UI elements (e.g., Web Components or Vue compoonents).
    Elements of the node modules that need to be used in an XWiki distribution can be bundled and exported in the webjar module of the same domain.

Please let me know what you think.
Thanks.

2

Sounds good to me.

Thanks,
Marius