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

3

I’d like to add a new type of module id node.
This id would be used for webjar that are only here to bundle a packages that is otherwise defined in xwiki-platform-node for publication on npm registries.

I uncovered the need for this type of module when working on the extraction of Live Data to make it reusable (see Extract Live Data to make it reusable outside XWiki).
During this refactoring, I need to introduce LD-specific packages. But I also need to distribute those packages as webjars in XWiki to make them reusable by other webjars without seeing the library code being duplicated in each webjar.

For instance xwiki-platform-livedata-node-ui is the webjar bundling @xwiki/platform-livedata-ui as a webjar, imported by xwiki-platform-livedata-webjar and xwiki-platform-notifications-webjar.

4

We have https://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HBuildBestPractices

Indeed, this has been agreed a long time ago but I don’t see it documented. Let’s add it.

+1

Just a question: why use the suffix only for modules that are published on npm registries? How do we name node modules that are not published?

LGTM.

Let’s update https://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HBuildBestPractices

Thx

5

Done, see https://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HBuildBestPractices