Mark,
On 8/29/24 09:14, Mark Thomas wrote:
On 29/08/2024 14:02, Christopher Schultz wrote:
Felix,
On 8/29/24 05:06, Felix Schumacher wrote:
Am 25. August 2024 10:36:44 MESZ schrieb Mark Thomas <ma...@apache.org>:
All,
You have probably seen that I am working on updating the UML
diagrams we have in the architecture section of the Tomcat
documentation.
The original diagrams were written in IBM Rational Rose. They were
donated by a contributor. I don't thnk any committer ever had access
to a license for IBM Rational Rose. That made maintaining them
difficult. I managed to find a tool to export them to SVG but they
are still very out of date.
My expectation is that architecture diagrams like this (and possibly
a few more) will be required to meet the CRA requirements. Even if
I'm wrong on that, there are other benefits to having up to date
diagrams explaining Tomcat's internal structure and how it works
such as helping new contributors find their way around the code base.
I've found a tool that appears to do everything we need and a lot
more with a free community edition - Visual Paradigm - that I have
been using to create updated diagrams. The tool is available for
Windows, Linux, Mac and has an on-line edition.
To ensure we don't end up in the same position as we did with the
previous diagrams, I think - as a minimum - we should take copies of
the installers for the community edition and put them somewhere safe
- I have access to an ASF owned Google Drive we could use.
The free version does everything that we want but it does watermark
the output when the diagrams are exported.
I have been wondering about the benefits of purchasing a license. A
perpetual license for the modeler version (the entry level) would
cost $99 for a single user. There is a floating license version but
that requires a license server to be installed. It is designed for
office LANs rather than global collaboration.
The main benefit of the license is that it means the exported
diagrams don't contain the watermarks (company logo in top-right
corner).
If we did want to purchase a license (in the name of the Tomcat PMC)
we could use the Google security funding since the primary driver
for this work is the CRA.
Thoughts?
Personally, I am leaning towards spending the $99 so we can remove
the watermark from the Tomcat docs.
Have you thought about using a tool like plantuml or mermaid-js?
That way the source would be human readable. Plantuml could probably
be added to the ant setup and would render SVG files or even ASCII art.
The files under architecture looked like sequence diagrams, which
should be doable.
If other tools are on the menu, there is always graphviz.
I'm happy to look at suggested alternatives.
I've had hit-or-miss results with graphviz. When it's willing to
generate a nice-looking graph for you, it's fantastic and easy to work
with.
When you can't get it to generate the graph you WANT, it's a total PITA.
Looking at what is required to generate a class diagram:
https://graphviz.org/Gallery/directed/UML_Class_diagram.html
that looks like too much hand-crafting is required. While PlantUML
didn't work out, I was able to produce something close within minutes.
I'm not even sure where I'd need to start with graphviz.
Yep, graphviz is definitely not UML-specific, it's ... like, its own
thing, man[1].
-chris
[1] https://www.youtube.com/watch?v=tML85kQfy0c
(Safe for work but not necessarily your sanity)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
