Good to hear some opinions from you all. Time to throw some of my own into
the mix.
1. Yes, I recommend that PlantUML be integrated for use to improve the
documentation in all Codehaus and Apache plugins (and therefore included in
their respective parent POMs). Why?
In my experience, the absolute majority of software documentation is
inadequate. Sometimes this seems caused by inadequate amounts of
documentation or examples, and sometimes it is caused by an excessive
amount of text without good, consise illustrations. "Excessive amounts of
text without good, consise illustrations" describes documentation at Maven
and Codehaus alike.
Why is this? Because programmers are not creative enough? Because there
are too few *good* tools to create images available? Because noone likes
stashing binary image data in a version control system designed to track
changes in text? Or maybe simply because it takes time and effort to care
enough to even suggest it?
I am fairly uninterested in the reasons why our documentation is so
text-heavy, but I want this to change for the better. All the introductory
courses in Usability Engineering point to the benefit of knowing a trifle
about memory and learning to be able to provide a better learning
experience for technology documentation in general. PlantUML is a good fit
for Maven documentation, since it:
1. Is used only when producing site documentation, and hence not
requires any attention from plugin developers on a programmatic level.
2. Reads text sources, implying generated binary images only exist in
the artifacts. This yields better version control mechanics for
images than
checking in the image binaries.
3. Provides a standard for generating non-textual documentation,
which - I strongly believe - should be *encouraged* by plugin
documentators. (Refer, for example, to the brief flow chart on
http://mojo.codehaus.org/jaxb2-maven-plugin/example_schemagen_postprocessing.html,
which provides a quick overview of the order of the post-processing
standard NodeProcessors).
Hence I believe that this is a non-intrusive addition which should go
into the maven and codehaus parents. Better that all use a standard set of
tooling for doumentation than that all plugin projects should set it up
individually - particularly because this requires some effort, which
implies that the quickest way is to not set it up and therefore not
improving today's documentation standards.
2. The main cost and time consumption in big projects tend to be
maintenance costs and tracking down exceptions, rather than various
problems occurring duting developement. Moreover Therefore, it is really
important that artifacts contain full dependency information - including
any transitive dependencies they were built with. Since the servicemix
depends plugin doesn't affect the plugin development at all - but simply
generates a single file below the META-INF directory - it is simple enough
to include in the parent POM to ensure that all plugins should use it.
What is the alternative way of harvesting this information? Oh ...
simply browse through the documentation of every plugin in the build, to
check its project dependency graph (or dependency listing) report to see if
you can find the dependency clash... Since the POM itself does not contain
any transitive dependencies information, you can't really use the POM in
the artifact JAR for anything beyond seeing the immediate dependencies.
So I suggest that we ensure that all our plugins (Codehaus and Apache
alike) are deployed with a dependencies.properties file as created by the
depends-maven-plugin. This is a quick and easy life ensurance which does
not create problems in the build, but instead helps to work around
shortcomings with the current POM format. The "usecase" for this is to save
time in tracking down errors (primarily in large builds).
3. I made the JavaDoc of the Jaxb2-Maven-Plugin adhere to the Java 8
doclint specs a few revisions ago. However, I have a testcase where I want
to ensure that a custom doctag is processed correctly in the
post-processing pipeline where the j-m-p injects XML document annotations
synthesized from JavaDocs. Hence I created a test class with javadoc
containing a custom javadoc tag.... which breaks the Java8 site build,
since the Java 8 doclint sees this as an "incorrect" javadoc tag.
Thus, it seems like a rather big problem if the doclint prevents us from
making fine-tuned testcases where javadoc plays a part - implying I would
suggest that we disable the doclint for *test-scope* JavaDoc (i.e. keep
the doclint setting on for the javadoc to be published in the javadoc
artifact). If you have other suggestions for how to fix this (beyond
"remove your unit test to please the doclint"), I'm all ears.
All right. Have to run to the train now...
:)
My suggestions still stand.
2015-02-10 14:26 GMT+01:00 Anders Hammar <and...@hammar.net>:
> I would recommend that we migrate to the following requirement for all our
>> plugins:
>>
>> 1. Minimum Maven version 3.0.4 (i.e. drop support for Maven 2.x)
>>
>> As discussed (and concluded) somewhere else, we should go with a Maven
> 3.0 minimum requirement. Unless there is a good technical reason for a
> higher version requirement.
>
>>
>> 1. Run ITs on JDK 1.6, 1.7 and 1.8 (i.e. require that codebase is
>> compilable with JDK 8, in addition to 6 and 7)
>>
>> Good! I also assume you include have a Java 6 requirement for the
> codebase in this statement? I think it's time to leave Java 5 behind.
>
> One other thing that might be a good time to start thinking about is Java
> 9. There is no Java 9 on Bamboo yet, but it would be good to start testing
> our plugins with that as soon as possible. I suspect that some plugins will
> be affected by the changes in 9.
>
>> *Added Mojo Parent capabilities*
>> Also, I would recommend upgrading the Mojo parent to augment some generic
>> site (and other) capabilities in the following manner (will write JIRAs for
>> this, but I want a discussion first):
>>
>> 1. Include PlantUML diagramming capabilities, such as is done in the
>> latest SNAPSHOT POM of the jaxb2-maven-plugin. PlantUML is a powerful tool
>> and can be used to draw illustrative diagrams of various sorts. This would
>> require two new variables in the Mojo Parent corresponding to the two
>> versions (plantuml and plantuml plugin) seen in the snippet below.
>>
>> Is this something that all mojos should use?
> I'm not totally fond of just shuffling loads of plugins into the parent
> unless it's something that should be used by all mojos. So if not it migth
> as well be handled per mojo.
> I'm also not happy with all these properties for handling one specific
> version. Many POMs are turning into Java programs with variables for every
> dependency's and plugin's version. Not thte Maven way IMHO.
>
>>
>> 1. Add the depends-maven-plugin to Mojo Parent, to ensure that all of
>> our plugins contain a simple-to-parse listing of all dependencies used to
>> build the plugin - including all transitive dependencies. This would
>> require one new variable in the Mojo Parent corresponding to the plugin
>> version.
>>
>> Is this something that all mojos should use? What's the usecase?
> As discussed in MJAXB-120 I see limited use of this info.
>
>>
>> 1. Define descriptions on how to create JDK 8-compliant JavaDocs. Or
>> - alternatively - disengage the lint checks for JDK 8, to ignore the
>> syntactic problems.
>>
>> Good! This is something that all mojos should handle.
>
>
>> The 3 enhancements above correspond to the pom snippet below; I would
>> deem these improvements as completely unintrusive for the plugin and hence
>> not problematic to add. Waddaya say?
>>
>
> No? :-)
>
> Also, please not that ${basedir} is deprecated and you should use
> ${project.basedir}.
>
> /Anders
>
>
>>
>> <!-- Generate maven dependencies listing file -->
>> <plugin>
>> <groupId>org.apache.servicemix.tooling</groupId>
>> <artifactId>depends-maven-plugin</artifactId>
>> <version>1.2</version>
>> <executions>
>> <execution>
>> <id>generate-depends-file</id>
>> <goals>
>> <goal>generate-depends-file</goal>
>> </goals>
>> </execution>
>> </executions>
>> </plugin>
>>
>> <!-- Provides PlantUML integration into site deployments. -->
>> <plugin>
>> <groupId>com.github.jeluard</groupId>
>> <artifactId>plantuml-maven-plugin</artifactId>
>> <version>7954</version>
>> <configuration>
>> <sourceFiles>
>> <directory>${basedir}</directory>
>> <includes>
>> <include>src/site/**/*.puml</include>
>> </includes>
>> </sourceFiles>
>>
>> <outputDirectory>${project.build.directory}/site/images/plantuml</outputDirectory>
>> </configuration>
>> <executions>
>> <execution>
>> <id>generate-plantuml-diagrams</id>
>> <goals>
>> <goal>generate</goal>
>> </goals>
>> <phase>pre-site</phase>
>> </execution>
>> </executions>
>> <dependencies>
>> <dependency>
>> <groupId>net.sourceforge.plantuml</groupId>
>> <artifactId>plantuml</artifactId>
>> <version>8017</version>
>> </dependency>
>> </dependencies>
>> </plugin>
>>
>>
>>
>> --
>>
>> --
>> +==============================+
>> | Bästa hälsningar,
>> | [sw. "Best regards"]
>> |
>> | Lennart Jörelid
>> | EAI Architect & Integrator
>> |
>> | jGuru Europe AB
>> | Mölnlycke - Kista
>> |
>> | Email: l...@jguru.se
>> | URL: www.jguru.se
>> | Phone
>> | (skype): jgurueurope
>> | (intl): +46 708 507 603
>> | (domestic): 0708 - 507 603
>> +==============================+
>>
>>
>
--
--
+==============================+
| Bästa hälsningar,
| [sw. "Best regards"]
|
| Lennart Jörelid
| EAI Architect & Integrator
|
| jGuru Europe AB
| Mölnlycke - Kista
|
| Email: l...@jguru.se
| URL: www.jguru.se
| Phone
| (skype): jgurueurope
| (intl): +46 708 507 603
| (domestic): 0708 - 507 603
+==============================+
