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

lfvjimisola commented 1 year ago

Short summary:

UPDATE: This comment https://github.com/repaint-io/maven-tiles/issues/21#issuecomment-111084067 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:

including a tile under plugin configuration in pom.xml or
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 commented 1 year ago

Examples are available here:

lfvjimisola commented 1 year ago

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:

https://github.com/redhat-developer/vscode-java/issues/594 (https://github.com/eclipse-m2e/m2e-core/issues/118)
Working along with BOMs
Handling of properties (shared between tiles and composites)

lfvjimisola commented 1 year ago

FYI. Bug https://github.com/eclipse-m2e/m2e-core/issues/118 has now been fixed.

lfvjimisola commented 11 months ago

@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 commented 11 months ago

@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 - @talios@mastodon.nz

talios commented 10 months ago

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 commented 10 months ago

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 commented 9 months ago

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.

repaint-io / maven-tiles

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