Software archeology - New Nagios SNMP Plugins release
A long, long, long time ago, I used to moonlight (well, actually daylight) as BoFH and during that time, I wrote two small plugins for Nagios. Five years later, this code is still in use and included in a number of mainstream Linux distributions.
And it still has an annoying compilation bug with gcc4. One that I know of since almost three years.
Today, one of these vendors actually forwarded me a patch they are using in their RPM. Cool. Time to cut a new release.
Get Nagios SNMP Plugins 1.1 while they are still hot. Have fun.
archeology c code GPL open sourceA journey through Maven Land
No, this is not one of my Maven rants, though it could easily be. This is however a short tale on how the Velocity site has been set up using Apache Maven 2 and a number of plugins written for Maven 2.
What I wanted to have is a site that pulls some information out of the Site POM and still uses the Maven 2 Site plugin and the reports to build.
In the end, I wrote for the site
- A Plugin that allows the Maven 2 renderer (Doxia) to render pages generated from Velocity templates (this is after all for the Velocity site…)
- A custom skin to get the look and feel of the old Velocity site, though it is already discusses as “antiquated”. But now it is only a simple matter of changing a CSS file. And generating the site with its own custom skin, allowed us to sneak in a RSS feed that you can subscribe to if you want to keep up to date with Velocity news.
- And finally a plugin that reads an XML formatted news file and builds teaser elements, a news page and (by using the amazing powers of the Rome library) create an RSS 2.0 feed about the news.
Nothing of that stuff is really Velocity specific, though it got created for the Velocity site and will stay here (under site/tools) for a while. Brett suggested the Maven sandbox but having experienced how stuff in Maven land moves like a quagmire in a hail storm, I do not want to put essential site building tools there (yet?).
Ah well, in the progress of that, I learned more about Maven, Plexus, Doxia and the rest of the zoo than I really wanted [1, 2, 3, 4, 5, 6, 7] and in the end I had to rewrite a part of the Doxia Decoration Model to get my reactor built site to get all the links and breadcrumbs right (You never heard of the Doxia Decoration Model? That is not really surprising. There are zero docs about it). But I said that I do not want to rant.
So in the end, yes: The resulting site is satisfying to me and hopefully also to our users. Comments welcome.
apache code maven velocityI’ve had it with Maven sites and xdoc!
Ah, Maven. Everyone who has ever met me in real life and talked to me about Maven, knows my love-hate relationship to this tool. Maven, just like Microsoft Windows, is deceptively easy to use. It is sometimes even shiny. It does things where you have to write lots of ant-script-lines in a few lines.
But if you scratch the surface and try to adjust maven to do what you want and it is not exactly the Maven way of doing things, you will find out that Maven is very good at breaking in exactly the wrong moment. Not because Maven is a bad tool. Not even because it was written with a mindset of forcing a personal Weltsicht on unsuspecting tool users. But because it was written partly in a language that frankly sucks at being usable for any real world work.
But I wanted to rant about Maven sites. Not Maven itself. Well, Maven sites. They look great. They are easy set up and contain all that meta-information that one wants to know about a project and it would talk a lot of ant wrangling to get all this informations in a whim:
- Javadocs
- File Activity, Developer Activity and SCM change log reports
- Code metrics
- Automated crud checkers such as PMD, Checkstyle and Findbugs
and the list goes on and on. But here comes the catch: Most of this information is volatile. It simply does no longer work if you want to go back in time and want to rebuild a site in a defined state.
This might stem from a philosophical point of view that some of the developers have. If you followed the Maven development (as I did because it somehow mushroomed out of the Turbine project) as closely as I have for a while, you might have noticed that up to 1.0 (or with the current 2.0 branch) the most important bit of advice from the developers was: Use the most current trunk version. The reluctancy to actually RELEASE a version, call it 1.0, 1.0.1, or 1.1 but to insist on working with unreleased SCM snapshots is like a red thread going all through maven development.
And here, the current maven site concept shines! Rebuilding the site from a trunk every few hours/days is perfect. You always have up-to-date information.
But it does not help you much. Because for a release you want to lock information in a state as it was when that release was made. Releases are about repeatability. About stability. And guess what: If you download a (maven-build) dist-src package, and rebuild the site, it no longer matches. And it doesn’t match in the most crucial parts: The changelog, File and Developer activity parts. So if you didn’t built a site at release time, then this information is all gone. You can never go back again!
And then documentation itself. Maven has this great concept of including xdocs. What are xdocs? They are documentation in a souped-up XML format which comes from the Anakia tool, that is part of the Jakarta Velocity Project. Writing about Anakia would warrant another rant, so I will can this here (I could go on for ages about missing documentation).
What is really bad is, that it forces not only XML on an user who wants to write docs, it also forces an unusual format on people. If you insist on XML, why not DocBook? There you can use a myriad of editors which hide the XML from you. Why Anakia? Oh yes, there is a docbook plugin. It is pathetic. It is so pathetic that the documentation for the DocBook plugin is written in… Anakia documents. The DocBook plugin can convert docbook files. But they are neither integrated into the maven site, nor do they look as nice as xdoc. I think you can imagine for yourself how well accepted or widely spread they are…
Why is it bad to force an unusual style and tight “builds best with trunk” integration onto documentation? Because it leads to rotting docs. Most developers don’t like writing docs. I don’t like writing docs. But if I have to, then I want to take an editor and chug away. No thinking about markup. If I want to _underline_ something then I want to do it in the text. Not with some obscure markup. Or opening and closing sections. And the “tight trunk integration” leads to these rotting docs dragged around everywhere. You don’t want this. You want your docs split up:
- Global Documentation - Docs about the Project itself. Maybe News, Releases, Talks, Awards. Global Links. Stuff that doesn’t change much
- Release specific Documentation - Change Logs, Code Metrics, Release Notes, Javadocs. Stuff that must be reproduceable whenever a specific release documentation site should be built. There is more than just “one global site at foo.org”. Think Intranet integration. Think team documentation sites.
- Development specific Documentation - Activity logs. Changes. Stuff that changes every few days. Probably only interesting for the main (internet) development site.
Does Maven support that kind of split up? Not at all. You have to split your docs into multiple maven projects (maybe tied together by the Reactor). You cannot link well between sites, because for “off-project” links, you must know the (full!) URL. You can’t use relative links because Maven won’t translate them. And the list goes on and on.
So you might ask yourself now: What good is the Maven site for? IMHO, for the metrics of a current development process. For the kind of development process, that you see in many open source projects that are developed at high speed but never have any official releases.
And what would I recommend to use for documentation? Even if you cry out loud now: I’d recommend a Wiki. Stop. But a Wiki suffers from the same problems as the Maven site. Yes, but every time you want to make a release, you snapshot your Wiki and then use a transformer to convert it into xdocs. And then bundle these xdocs with the release. This doesn’t help you with the volatile change log and activity issues when rebuilding the release site. But it will help you tremendously with keeping your documentation up to date. Of course, building usable project documentation in a Wiki is a thing, that I don’t want to go into here. Let’s just say that you might want to have a Wiki Gardener on your team. But this is a job that can be done by someone who wants to contribute without coding skills.
In some maven-site based projects that I work on, this is clearly visible. While code development happens in the SCM, the docs buried there (as xdocs) rot away pretty heavily. At the same time, new documentation is added to the related Wikis all the time. Because it is easy. Because it is convenient. Because it works. And xdoc does not.
apache code maven xdoc