How to document parent Maven modules on extensions.xwiki.org

Development
1

Hello,

Context

While documenting Live Data, Eleni noticed that our e.x.o pages don’t mirror the repo structure: Like Application and XWiki Platform - Like - API are siblings, with no parent page listing the children (Matrix discussion).

The rule is one e.x.o page per extension id, organized like the repo. What we lack is an agreed way to represent the parent Maven module (the aggregator pom) on e.x.o.

The two mechanisms we have

1. Project page (e.g. Live Data) — a dedicated page type (ExtensionCode.ProjectClass), separate from extension pages. The concept, its xclass and its sheet came out of a hackathon and were never discussed publicly; Thomas added the auto-update of the metadata from Maven later. The page itself still has to be created by hand, there is no auto-create.

2. pom-packaging extension import — importing the parent pom as a regular extension, i.e. an extension with no associated file whose point is to list its dependencies. This is already supported by the e.x.o Maven import, and such an extension shows up with the “No file” type. What’s missing is a UI at import time listing the submodules, so that you can choose which children get imported along with the parent.

The question

To me these are the same concept: a container grouping children extensions. So why two different xclasses? A pom extension type could simply get its own sheet and display what a Project page displays today.

Thomas disagrees: “Projects and extensions are really different things even if they have some metadata in common”, they are two completely different xclasses.

My worry is that if we keep creating Project pages by hand now and later move to pom extensions, we’ll do the work twice.

One possible reason for the split is that the extra Project metadata doesn’t exist in pom.xml today. That looks fixable with custom Maven properties, and we need something like a notion of entry points in EM anyway.

Side note: before importing a parent pom we need to fix its EM metadata in the pom.xml (name, description), otherwise we get an ugly name on e.x.o.

Options

  1. Project pages only: keep the current concept and add auto-create from the Maven import.
  2. pom extensions only: drop Project pages, add the submodule-picker UI plus a dedicated sheet for the pom type, and move the missing metadata into pom.xml.
  3. Both, as complementary things: the Project page stays the hand-curated, human-facing container while the pom extension is the Maven-derived artifact page. This needs a clear rule saying which one to use when, and a way to keep them from diverging.

What I’d like us to decide

  • What does a Project actually carry that a pom extension cannot? Concretely: which fields, and which behaviour?
  • If the answer is “nothing we couldn’t put in the pom.xml”, do we go for option 2 and stop creating Project pages?
  • If we keep both, what is the rule for contributors: when do I create a Project page, and when do I import the parent pom?
  • And, if we go that way, is “No file” the right name for that type on e.x.o?

Independently of the outcome, none of our e.x.o rules (one page per extension id, mirror the repo, parent pages) are written down anywhere. I’d like them documented on dev.xwiki.org and linked from contrib.xwiki.org and from the Doc Guide.

Opinions welcome, especially from anyone who has had to document a multi-module extension recently. I’d like us to settle on a way forward rather than keep doing it by hand each time.

Thanks!

2

You are mixing two very different things. It’s either an extension that you install to get the dependencies listed in it (so the current behavior), or a parent (concept that does not exist in e.x.o currently, we have a root concept with the project, but it’s not the same as a parent you can have at any level), being both at the same time would not really make much sense for e.x.o use case.

3

I still don’t understand. A pom module is an extension (or can be considered an extension), like a jar module or a xar module. This is what exists at the Maven level (packaging = {pom, jar, xar}). I don’t know if that’s what is implemented in EM, but if not, I don’t see why EM couldn’t consider a pom an extension. That would certainly make the most sense to me and it would create a symmetry with Maven.

OTOH the concept of “parent” doesn’t exist as an maven artifact type (in XWiki language, a parent is not an extension). It’s just a relationship, similar to dependencies but upward instead of downward. So you can’t install a “parent”, that doesn’t really make sense to me (since it’s not an extension).

What am I mixing?

Thx

4

Hi,

From a documentation point of view, I don’t have a preference on the mechanism (Project page or pom extension). What I need is:

Thanks!

5

Thanks Thomas, I understand now: a pom module can be a dependency bundle (installable, today’s “No file” extensions) or a parent/aggregator (never installed, its <dependencies> are inherited by children rather than “contained”). Importing aggregators as regular extensions would mix the two, so let’s not do that, and keep Project as the representation of aggregator modules. Small correction to my first post: Live Data is actually a hand-made extension page for xwiki-platform-livedata, not a Project page (Documentation is a good example of an imported Project, with the parent pom id as its id).

What’s left to decide is the hierarchy. Today Projects are used at a single level, with the extensions nested below them. Options: (A) one Project per top “large module”, with all its extensions flattened under it, deeper aggregators (e.g. notifications-filters) getting no page; (B) one Project per aggregator pom, nested to mirror the Maven module hierarchy. I’d go for B: simplest rule for contributors (every aggregator pom = one Project page, placed like in the repo) and it maps 1:1 to the import. Also, the Project sheet lists extensions by location prefix, so a top Project already lists all its descendant extensions (checked on Extension.Extension, which lists the extensions of its nested Security Project), meaning the flat view comes for free. We’d only need to add a “Sub-projects” section to the sheet, since nested Projects themselves don’t show up in that list.

Since ProjectClass and its sheet currently only exist on e.x.o, I propose moving them to the Repository Application, so that the Maven import can auto-create/update Project pages for pom modules and place the imported children under them.

WDYT?

6

Hi,

Currently on exo there are contrib extension pages containing the ProjectClass and being also pom pages, e.g. Cristal Integration. These are the extension pages that are Project/pom pages: Extension Pages.

+1 for mirroring the module hierarchy.

Thanks!