[DOXIASITETOOLS-348] Allow to enforce a parent site descriptor

[kwin]

No description provided.

[kwin]

not sure this is really a good name, any other suggestion?

[michael-o]

Instead of enforce I'd use the term require. E.g., requireParentSite. The term descriptor is too confusing and too abstract for most.

[kwin]

Should probably outline that this is only effective in case the the POM has a parent defined. Also this just requires a parent descriptor on any level (not necessarily from the direct parent).

[michael-o]

I have a few thoughts on this, will try to share tomorrow or over the weekend.

[michael-o]

Looking at your usecase I have the feeling that we have a conceptual flaw in our design. Implicit parents do not seem right after all and you are trying to remedy this with a parameter at the wrong place IMHO. I think that we either need something like:

<site>
  <parent>
    <groupId>com.mycompany.app</groupId>
    <artifactId>my-app</artifactId>
    <version>1</version>
  </parent>
</site>

(type and classifier are implied)

or we can make the site.xml a provided dependency of our build in the POM directly. If the site descriptor follows the rules of the POM then introducing a parent seems natural to me, no?

See this one: https://repo1.maven.org/maven2/org/apache/maven/maven-parent/43/maven-parent-43-site.xml

Either:

<site>
  <parent>
    <groupId>org.apache.maven</groupId>
    <artifactId>maven-parent</artifactId>
    <version>43</version>
  </parent>
</site>

OR

<project>
<dependencies>
  <dependency>
    <groupId>org.apache.maven</groupId>
    <artifactId>maven-parent</artifactId>
    <version>43</version>
    <type>xml</type>
    <classifier>site</classifer>
  </dependency>
</dependencies>
</site>

WDYT?

[kwin]

we have a conceptual flaw in our design

Yes, but I am trying to fix this without breaking backwards compatibility.

Having an additional parent on the site.xml level would fix this, but in most cases is highly redundant (and also isn't properly upgraded during release), so maintaining this on site.xml level would lead to a lot of additional challenges.

Similar an additional dependency on the POM level feels highly redundant, because this should always reflect the Maven coordinates of the parent. Also knowledge about classifier (potentially extended with locale) requires additional knowledge from consumers they shouldn't necessarily know about.

So just having a boolean toggle is IMHO the option with least redundancy and simplest to understand from a consumer PoV.

[michael-o]

we have a conceptual flaw in our design

Yes, but I am trying to fix this without breaking backwards compatibility.

Having an additional parent on the site.xml level would fix this, but in most cases is highly redundant (and also isn't properly upgraded during release), so maintaining this on site.xml level would lead to a lot of additional challenges.

Similar an additional dependency on the POM level feels highly redundant, because this should always reflect the Maven coordinates of the parent. Also knowledge about classifier (potentially extended with locale) requires additional knowledge from consumers they shouldn't necessarily know about.

So just having a boolean toggle is IMHO the option with least redundancy and simplest to understand from a consumer PoV.

Let me crunch on this...I am we are already breaking stuff. This would be ideal for now because we won't have another chance soon to break it.

[michael-o]

Instead of enforce I'd use the term require. E.g., requireParentSite. The term descriptor is too confusing and too abstract for most.

[michael-o]

Well, it is a compromise...let's move on.