todo and changes documents

[David Crossley <cr...@indexgeo.com.au>]

Piroumian, Konstantin wrote:
> > Konstantin wrote:
> > > Steven Noels wrote:
> > > > There is...: http://marc.theaimsgroup.com/?l=forrest-dev
> > >
> > > Thank you.
> > >
> > > So, the next questions are (after co from CVS):
> > > Where do I start? Is there any ToDo list or description of
> > > goals/tasks?
> >
> > Not really, use these as starters:
> >
> > http://marc.theaimsgroup.com/?t=101441112100004&r=1&w=2
> > http://marc.theaimsgroup.com/?t=101465347800003&r=1&w=2
> > http://marc.theaimsgroup.com/?t=101431907500006&r=1&w=2
> 
> Thanks once again.
> I've found also project-info.xml in xml-forrest root with a brief
> description. What about of using it instead of index.xml?

Welcome to the project Konstantin. Most of the *.xml docs
that you see are just placeholders, especially index.xml
One of the next steps is to provide some flesh to those bones.
We should talk about index.xml in a separate thread.

Forrest used to have a todo.xml and a changes.xml and
a developers.xml ... I have been meaning to ask about this
for a while, so now seems appropriate.

When the xml-forrest CVS was recently given a build
structure, those three documents were moved into
project-info.xml ... i do not understand why this happened.

We do have separate DTDs for both Todo and Changes, but
there is no DTD to specify the structure of project-info.xml
This seems like mixing of concerns to me, and i do not see
how the documents can be validated now. Furthermore, i
do not see how the build process can generate the separate
"To Do" and "Changes" pages. It seems that we would need
a special Cocoon sitemap entry to extract them first.

Should we go back to having documents that are separate,
visible, and controllable?
-- David

Re: todo and changes documents

[Nicola Ken Barozzi <ni...@apache.org>]

From: "David Crossley" <cr...@indexgeo.com.au>

> Piroumian, Konstantin wrote:
> > > Konstantin wrote:
> > > > Steven Noels wrote:
> > > > > There is...: http://marc.theaimsgroup.com/?l=forrest-dev
> > > >
> > > > Thank you.
> > > >
> > > > So, the next questions are (after co from CVS):
> > > > Where do I start? Is there any ToDo list or description of
> > > > goals/tasks?
> > >
> > > Not really, use these as starters:
> > >
> > > http://marc.theaimsgroup.com/?t=101441112100004&r=1&w=2
> > > http://marc.theaimsgroup.com/?t=101465347800003&r=1&w=2
> > > http://marc.theaimsgroup.com/?t=101431907500006&r=1&w=2
> >
> > Thanks once again.
> > I've found also project-info.xml in xml-forrest root with a brief
> > description. What about of using it instead of index.xml?
>
> Welcome to the project Konstantin. Most of the *.xml docs
> that you see are just placeholders, especially index.xml
> One of the next steps is to provide some flesh to those bones.
> We should talk about index.xml in a separate thread.
>
> Forrest used to have a todo.xml and a changes.xml and
> a developers.xml ... I have been meaning to ask about this
> for a while, so now seems appropriate.
>
> When the xml-forrest CVS was recently given a build
> structure, those three documents were moved into
> project-info.xml ... i do not understand why this happened.

;-)

I't a test, to see how-if you like it.

> We do have separate DTDs for both Todo and Changes, but
> there is no DTD to specify the structure of project-info.xml

As I stated in a previous mail, it's wanted, because I wanted you all to
add-remove what you deem best in order to have it just right. It sould have
a DTD, and it will.

> This seems like mixing of concerns to me, and i do not see
> how the documents can be validated now.

Now they cannot be validated of course, but it will.

The point is: what do you prefer?

I think that having a sinle project descriptor is more clean (one file
only), easy to find (don't have to ask in which file what I need is),
consistent (no need of external entities for common info, like developers),
and eases the usual clutter in the project root dir.
IMV, it's made to be as a modern version of the STATUS file that is
requested by the Constitution but seldom updated by some projects, or even
present.

As always, the main problem with these files is their regular update.
For this, I would prefer that the changes are clearly written in CVS commit
messages, and can be extracted automatically from there.
We can decide on a convention, like having to write, at the beginning,
something like "[NKB,bugfix] Description" (who, what type, what). It should
be easy to make a script in CVS that accepts only this format of messages
and rejects non conformant descriptions.
As for TODO, it shoudn't be a problem keeping it inside projectinfo.

What do you guys think?

> Furthermore, i
> do not see how the build process can generate the separate
> "To Do" and "Changes" pages. It seems that we would need
> a special Cocoon sitemap entry to extract them first.

It's not a problem. Three stylesheets and three "style" tasks are all that
is needed.

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------