On 11/07/2009, at 12:27 AM, Jason van Zyl wrote:
* push all release notes into docs/$version/release-notes.html
instead of the consolidated older format and add a page to list
them in order
So if someone wants to see the historical list of changes they will
need to look at N documents? The consolidated format is good as the
history of change is kept in one place which is what people looking
to migrate want to see.
Actually, yeah, I'm more in favour of accumulated notes for the same
reasons Jesse pointed out (though still deploying separate versions
that grow, and maybe starting to trim back over time if appropriate).
Would that make sense?
* set the release up to publish the above site and javadoc/xref at
release perform time (this is before the vote, but as it is
versioned it is not going to be live)
If you mean coupling the publishing of site during the release then
-1.
The site publishing cannot be coupled to the actual release. The
release of the binaries should not fail because of some aggregation,
ordering or some other problem with the reporting/site system.
Whoever is doing the release can do this in two steps. Some external
system could orchestrate this but the actual release itself should
not couple the site publishing the distribution of binaries.
I'm not sure why this is an issue - it's only a small sensible subset
of the site (javadocs and source xref). The problem at the moment is
that even though its in the release instructions it tends to get
skipped because only release:prepare/perform is remembered. If it can
be bundled in there (but disabled if desired), doesn't it make sense
to do in one hit?
The downside of the separate site approach is that the release
notes drop the main navigation (but there is a "Documentation" link
back to the main site). I don't think this is a bad thing.
Any objections to continuing this approach with Maven 2.2.x, and
perhaps making similar attempts on the plugins?
As bad as the site is now people are accustomed at least to the
structure. I really think you should think hard about wanting to
flip all this around again. The problem on the site is the content,
not the structure. There is actually far too much structure are far
too little meaningful information. I honestly don't think this is
the best use of anyone's time and the focus should be simplification
and clarifying the existing content more then anything.
I don't think my purpose was clear - this is about removing the
fiddling with release notes and versions on the site when a release is
done, which has required quite a bit of clean up after the last couple
of releases. As John said, there's too many moving parts, so this was
partially an attempt to automate as much as possible, and structure it
so further automation (like updating the release notes from jira at
release time) could make sense. I'm not trying to change the
documentation structure at this stage. Though I do think versioning it
makes sense, you're completely correct that the first focus needs to
be on content if work is done there.
Cheers,
Brett
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
