[docs] Would it be possible to provide some more extensive documentation with examples and best practices?

[lfvjimisola]

Short summary:

UPDATE: This comment #21 (comment) helped me a lot to understand composite, tiles etc.

I've spent a good couple of hours trying to see how we can use Maven Tiles with our setup. It is still not clear to me.
The lingo is somewhat new with things such as reactor build, multi-module build, composite poms, inherit config etc.

Don't think we have a difficult use-case but I'm feeling like and I'm doing something wrong. And it is not obvious for me how it should be structured from reading the documentation.

I know that an issue is not an ideal place to have a disussion, would you consider activating GitHub Discussions for this project, so that we can help each other out there?

I've checked: #21 #52 #69

Long(er) summary:

I would be really useful if the tiles mentioned under Composing Build functionality
are available as examples. An example project that covers most cases.

The project README mentions "Richard and Mark will be putting together a short book with tutorials for a better approach to building using Maven, but this is the short explanation" - is available somewhere?

From the README it's unclear to me what the difference is of:

1. including a tile under plugin configuration in pom.xml or
2. including within in tile.xml

Things that I'm currently find challenging and where I think documentation would be useful:

• properties: Shall they always be in tile.xml? Is there a difference if we place them in pom.xml or tile.xml?
• I currently have some properties that are placed in a tile.xml and they are available in another tile (that has this tile a dependency)
• Spring Boot sets version using , how do we do that in the right way? We currently have two different tiles that needs to use the same Spring Boot versions setting.
• How do I set maven plugin versions it the correct way? E.g. Maven Plugin versions are typically set expclitity (see below). E.g. setting versions for maven-compiler-plugin/maven-surefire-plugin/etc can be done e.g. in a java-tile w/o using pluginManagement, but I'm not sure where to do it for maven-clean-plugin, maven-install-plugin etc. Those are not links to Java but rather just Maven. Is a composite for maven (with pluginManagement) the solution and if so, is that composite also a tile, do I use regular or include it as tile dependency? (I haven't been able to get it to work yet)

<pluginManagement>
    <!-- 
        lock down plugins versions to avoid using Maven defaults, in alpabetic order
        for latest versions see: https://maven.apache.org/plugins/index.html
    -->
    <plugins>
        <!-- standard Apache Maven plugins -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-clean-plugin</artifactId>
            <version>3.2.0</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version>
            <configuration>
                <source>17</source>
                <target>17</target>
                <release>17</release>
                <encoding>UTF-8</encoding>
                <showWarnings>true</showWarnings>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-deploy-plugin</artifactId>
            <version>3.0.0</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-install-plugin</artifactId>
            <version>3.1.0</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>3.3.0</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-project-info-reports-plugin</artifactId>
            <version>3.4.1</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-resources-plugin</artifactId>
            <version>3.3.0</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.12.1</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.0.0-M7</version>
        </plugin>
        <plugin>
            <groupId>org.sonarsource.scanner.maven</groupId>
            <artifactId>sonar-maven-plugin</artifactId>
            <version>3.9.1.2184</version>
        </plugin>
    </plugins>
</pluginManagement>

I'll try to explain our use-case:

We currently use standard Maven inheritance and it's troublesome to say the least....

We have 3 different POMs that are used for releasing artifacts: standard library, spring boot library and spring boot application.

We would like to use tiles to handle:

• common things such as javadoc, testing, compile etc.
• spring boot library dependencies: used by both SB library and application
• spring boot plugin: used only by SB application
• for various dependencies such as camel, openapi/springdoc etc: i.e. if a project uses OpenAPI it should just be able to refer to the openapi tile for dependencies and plugin configuration

[lfvjimisola]

Examples are available here:

• https://github.com/repaint-io/maven-tiles-examples/tree/master/tiles
• https://github.com/OpenSourceNZ/osnz-java-tile

[lfvjimisola]

And my PoC of Maven Tiles for our use-cases and the review of two other developers our team has just decided that we won't use Maven Tiles as of now. We are afraid that we end up with other stuff that won't work for us (such as integration with VS Code).

It would be really good if the Maven Tiles README was updated with known limitations/workarounds such as:

• Incorrect source level detected using tiles-maven-plugin redhat-developer/vscode-java#594 (Bug 486737 - Support for Maven Extensions (LifeCycleParticipants) eclipse-m2e/m2e-core#118)
• Working along with BOMs
• Handling of properties (shared between tiles and composites)

[lfvjimisola]

FYI. Bug eclipse-m2e/m2e-core#118 has now been fixed.

[lfvjimisola]

@talios Is this project still alive? We picked up this trail now that the bug in eclipse-m2e has been fixed but are struggling a bit due to lack of documentation. Is there a forum/chat for asking questions?

[talios]

@lfvjimisola it is still alive - documentation still remains something I really work on. Forum/chat - as for a chat - there was the old Gitter we had, which I see has moved to matrix now - #repaint-io_maven-tiles:gitter.im - or you could find me on Discord (taliosnz) or twitter (@talios) - or mastodon - @[email protected]

[talios]

I've resurrected the github pages with new docs at https://repaint-io.github.io/maven-tiles - this is currently sitting on a feature branch and hope to flesh out some more docs shortly.

At the moment it's basically the README reworded/and chunked up.

[lfvjimisola]

Great. Our are incorporating Maven Tiles now. We could give feedback here on what we think would be useful to add if that is of interest.

An up-to-date example/demo project, ready to clone, would of course be useful.

[talios]

I've finally merged/setup Astro Starlight docs at https://repaint-io.github.io/maven-tiles and plan to add a bunch of example tiles, first off the deck will be a release tile based on recent changes/fixes with dependencyManagement.