Re-introduce PlantUML

[kriegaex]

Background

In the AspectJ.dev fork, a while ago I managed to PlantUML incl. Graphviz running on all Java versions 8-16 and all operating systems (Windows, Linux, MacOS) used for CI builds. In a first step I had used two different plugins, one for older and one for more recent OS. Then I forked one of those not so well-maintained Maven plugins, fixing some things and publishing it on Maven Central with under group ID dev.aspectj. So one plugin works in all situations. The resulting UML file is embedded in the Maven site section about multi-module builds, while image gneration was removed from this repository on purpose, supposedly not providing any value. I disagree. The diagram is helpful.

Suggestion 1: use status quo from AspectJ.dev fork

I can prepare a PR, porting the build and CI workflow settings to this repository.

Advantages:

• Immediate availability
• The most recent Windows versions of PlantUML have a basic Graphviz version embedded, i.e. on Windows Graphviz does not need to be installed. If we would use Windows for Maven site generation, the loss of time due to Graphviz installation in the CI workflow would be zero.

Disadvantages:

• On Linux and MacOS, Graphviz still needs to be installed. But we can skip the UML generation step in the CI workflows on those platforms.

Suggestion 2: switch to Java-based graph generation

The latest versions of PlantUML contain a new Java-based "jdot" engine called Sematana. I tested it with the UML diagram used by AspectJ Maven, the result looks very similar to the one generated by GraphViz. Only the layout is more dense with regard to spacing and resulting length of arrows. For me it looks acceptable, even though I like the GraphViz version a bit more.

Advantages:

• We could generate diagrams on all OS platforms without GraphViz installation, speeding up the build
• No need to add any time-consuming GraphViz installation steps to CI builds, not only on Windows but also on MacOS and Linux.

Disadvantages:

• I would have to upgrade the PlantUML Maven plugin or at least override the PlantUML dependency in our POM. Both would work and be easy.
• We would have to add a line !pragma layout smetana to the diagram source file. Also easy.

UML diagrams

If you want to compare, here are the two diagrams.

Graphviz

Smetana (Java-based)

[bmarwell]

I disagree. The diagram is helpful.

Can you state in which cases it is helpful? I am not against this PR per se, but I would like to see a problem which is actually fixed/solved here.

Suggestion 1 […] On Linux and MacOS, Graphviz still needs to be installed. But we can skip the UML generation step in the CI workflows on those platforms.

Or we could use a profile.

Suggestion 2 […]

Sounds better to me. Reproducible and reliable builds are valued very highly these days. An unknown binary version of an executable, possibly os-dependent, would not be helpful here.

I would still make it a profile for quick local testing, though.

[kriegaex]

The diagram is helpful.

Can you state in which cases it is helpful?

In order to understand the multi-module setup better, as it is an illustration of same.

I am not against this PR per se, but I would like to see a problem which is actually fixed/solved here.

If better documentation is not good enough a reason for you, feel free to close the PR. Then I am going to simply keep it in my fork. Why are you asking me to explain the obvious?

Or we could use a profile.

A profile for what? I made it work on all platforms. It might make sense to move the UML generation to the pre-site phase, though, then it would only be generated if you actually want to build a site.

Suggestion 2 […]

Sounds better to me. Reproducible and reliable builds are valued very highly these days. An unknown binary version of an executable, possibly os-dependent, would not be helpful here.

Where I come from, winners find a solution for every problem and losers find a problem in every solution.

I tried so hard to make you guys a bit more open-minded, and was dismissed so many times. Then you guys with your sense of entitlement came along, claiming to maintain this plugin again, urging me to give up my fork, which is still ahead of yours to some degree functionally. I asked for a personal, interactive talk with the team in order to make a plan together, so we can unify the projects again. Again, I was ignored. Next, I created PRs, even though I knew it was a bad idea without talk before. All I get as a response is being micro-managed and criticised for the smallest of reasons. You are all really making it quite hard for me to let go of the fork, but I am not going to do so, as long as I am not content with the state of this version, because a few enhancements which might be meaningless or worthless to you are quite meaningful (because helpful) for me. I am so fed up with this process. Whatever collaboration I am offering, you are just depreciating it by your condescending comments. Close the ticket or accept a PR, I no longer care. But never ever say it is my fault that we cannot have a unified plugin version. I tried so hard. No more. You have been the friendliest of the people I dealt with here, so thanks for that. But even with you I do not wish to work like this. Never for a minute I was treated like a peer here, and that is something I shall never accept if I spend time on contributing to an OSS project.

[olamy]

sounds very useless documentation. How maven multi modules works is explain really better in so many different websites or books. It's just generate very over engineering and over complicated documentation.

[kriegaex]

@olamy, you have made it abundantly clear before that you find it superfluous, so I am not surprised.

The UML diagram, however, does not explain general Maven multi-module basics, but it explains the relationship of POMs in this specific example, before listing same POMs + sample code. What is wrong or superfluous about illustrating something in a picture instead of just by a big wall of text? Documentation is for users, some of them first-time users of this plugin. They know less than Maven Core or AspectJ Maven contributors. We write documentation for them, not for ourselves. Furthermore, applying AspectJ to a multi-module project is not the same as simply compiling a multi-module Java project with Maven Compiler. It adds a layer of complexity, because users need to learn dealing with parameters like aspectLibraries or weaveDependencies. This is by no means trivial, until you used it several times and do not need the manual anymore.

I would argue, it would even make sense to optionally use more illustrative diagrams in other places, but at least in this most complicated example, it is justified.

You know, I am the one here who does a lot of community support on StackOverflow (SO), and if people do "copy & paste programming", but do not really understand the stuff they are copying, I have more work to do. I answered several questions related to multi-module AspectJ Maven before, and during that time image generation was already broken, so many users never had the chance to see the diagram that the original maintainer committed to this repository here many years ago. I remember, it helped me back when I started using AspectJ in Maven (before I only used AspectJ from Eclipse or from batch files, like most beginners). While it would by no means guarantee that lazy users would not simply ignore it and still do copy & paste programming, before asking me on SO, at least it would give them a chance to understand better and me a chance to link to existing documentation, telling them to RTFM instead of having to explain the content of the diagram in my own words.

[bmarwell]

@olamy it is no use. I kindly asked for a use case, out of curiosity. I got a personal attack as an answer. If there is a good reason, Alex does not want to share it with us. I bet it is good documentation in this case (pom relationships). He just does not want to make clear, why it especially useful in this case.

[kriegaex]

@bmarwell, I already explained in detail why it is useful, responding to both you and Olivier. Please be so kind as to read again.