Carsten Ziegeler wrote:
Reinhard Poetz wrote:
We have to find some way to mange the changes information between versions of
our different modules in Cocoon 2.2. In Cocoon 2.1 we use the status.xml based
on the status DTD. At the documentation creation process, Forrest integrates it
into the docs.
For 2.2 I can think of 3 alternatives:
- Continue using status.xml, setup one in every module and write a Maven
reporting plugin that adds them to the documentation
- Use the Maven changes format and also have one document at each module.
The reporting plugin for this format already exists but it doesn't allow
mixed content in the description element.
- Use Daisy. Create a new document type called "ChangeItem". This document
type contains information about the module and the version it belongs to,
the type (add, update, etc.), the person responsible for the change, etc.
Daisy provides powerful queries to create reports which can be integrated
into the existing documentation.
As I'm not a big fan of writing documents in XML by hand, I will setup the
necessary infrastructure in Daisy so that we can play with it and form an opinion.
Any thoughts, ideas?
Currently we have a status.xml for each block in trunk already which
lists (should list) changes between 2.1.x and 2.2. I think it is far
easier to keep track of changes (= add a comment to the changes
document) if it sits right next to the code that was changed. Today,
status.xml is not kept accordingly in all cases and I really fear noone
will ever add changes to some document stored somewhere else (in Daisy
for example).
I think it's not a matter of how I edit the document but more a where do
I edit it. Handling the changes xml document really requires a minimum
of XML as you just have to add an entry element and add your text inbetween.
IMO the changes notifications should be part of the documentation. This has the
advantage that both can easily refer to each other. But I see your argument too.
What do others think?
BTW, here is an example report of the Maven changes report plugin:
http://cocoon.zones.apache.org/dev-docs/core-modules/core/2.2/changes-report.html
(don't know why the icons are missing).
--
Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
--------------------------------------------------------------------
