You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@maven.apache.org by Brian Ewins <Br...@btinternet.com> on 2002/12/23 11:59:04 UTC
Report registration was Re: How to skip changelog step in site:generate?
dion@multitask.com.au wrote:
> Brian Ewins <Br...@btinternet.com> wrote on 19/12/2002 04:01:04 AM:
>
>>To get this to work, I was hoping to be able to define a jelly tag that
>>would do the work of writing the descriptors. I reckoned I'd implement
>>this by merging descriptors directly into maven-reports.xml, like so:
> So this would be a report:display-all type of tag, yeah?
No, more like a 'display-one'. See the code below.
>>However obviously I don't know enough jelly - how would I wrap this up
>>in a jelly 'define:tag' tag? And how do I emit properly escaped xml for
>>the description? Any ideas?
> The register tag would have to store the entries in the jelly context, and
> the display-all tag would have to simply write them out.
>
> Does this help, or do you need more info on define:tag itself?
A little more help - I've written the code (which is probably best
merged into something like the xdoc plugin, though the copying of
maven-reports.xml would need changed). Problem areas are marked inline,
sample tag usage shown at the end.
<goal name="report"
description="Set up jelly tag for registering reports"
prereqs="report:init"/>
<!-- NB prereq of init-dvsl-tag means maven.gen.doc is set -->
<goal name="report:init"
description="Set up jelly tags for reporting."
prereqs="init-dvsl-tag">
<mkdir dir="${maven.gen.docs}"/>
<!-- create empty report index if none exists -->
<copy file="${plugin.dir}/templates/maven-reports.xml"
todir="${maven.gen.docs}"/>
<define:taglib uri="report">
<define:tag name="register">
<!-- FIXME: Why is maven.gen.docs null here? -->
<j:set var="maven.gen.docs"
value="c:\maven_projects\iforms/target/generated-xdocs"/>
<!-- I have to use a filescanner so that toURL will work -->
<fileScanner var="docFiles">
<fileset dir="${maven.gen.docs}">
<include name="maven-reports.xml" />
</fileset>
</fileScanner>
<j:forEach var="file" items="${docFiles.iterator()}">
<!-- read the current index in -->
<!-- FIXME: all the trim=false's here arent enough
to get the output xml to behave. There is a bug
in prettyprint dealing with mixed content. See
examples at end -->
<x:parse var="doc" xml="${file.toURL()}" trim="false"/>
<!-- write new index out -->
<j:file name="${file.absolutePath}" prettyPrint="true">
<jsl:stylesheet select="$doc">
<!-- Insert report description -->
<jsl:template match="table">
<jsl:copy trim="false">
<!-- reports are (obviously) unique by location -->
<jsl:applyTemplates
select='tr[not(td/a/@href = $reportLocation)]'
trim="false"/>
<tr>
<td>
<a href="${reportLocation}">
${reportTitle}
</a>
</td>
<td><define:invokeBody trim="false"/></td>
</tr>
</jsl:copy>
</jsl:template>
<!-- next two templates are not quite the
identity transform. (comments, PIs not
preserved). I tried to just re-prefixing
the xsl version, but it might not have worked
at the time because of other problems. I'll
look at this again
-->
<jsl:template match="*" trim="false">
<jsl:copy trim="false">
<jsl:applyTemplates trim="false"/>
</jsl:copy>
</jsl:template>
<!-- ? this looks odd. -->
<jsl:template match="@*"/>
</jsl:stylesheet>
</j:file>
</j:forEach>
<!-- todo: should log at this point -->
<echo>Registered report: ${reportTitle}</echo>
</define:tag>
</define:taglib>
</goal>
Sample usage:
<attainGoal name="report:init"/>
<!-- test: bar and baz should appear, not foo. -->
<report:register reportLocation="rep1.html"
reportTitle="Report 1a">Foo</report:register>
<report:register reportLocation="rep1.html"
reportTitle="Report 1b">Bar <a>test</a> spacing</report:register>
<report:register reportLocation="rep2.html"
reportTitle="Report 2">Baz <a>test</a> spacing</report:register>
The xml output doesn't space correctly because of what is certainly a
bug in the 'prettyPrint' option of the jelly:core 'file' tag (and may
well have been fixed; my copy of b8 is a couple of weeks old). Turning
on and off prettyprinting removes space after tags in mixed content:
'Baz <a>test</a> spacing' becomes 'Baz <a>test</a>spacing'. Turning
'some space' into 'no space' isn't what a prettyprinter should do,
especially when I've marked every single node with 'trim=false'!
Anyway as you can see, I didn't 'store the entries in the jelly context'
- merging them on disk was something I understood well enough in xsl,
and I have no idea how to put anything into 'the context' as there's not
much documentation to go on. When in doubt I just tried whatever I could
find samples code for.
A register/display-all design would have been faster, but as I only know
how to get jelly to use global-but-immutable properties or
mutable-but-local vars I can't see how to implement that.
This might explain why I can't figure out whats wrong in the first
'FIXME' above, where maven.gen.docs is null :). jelly:define:tag would
make a lot of sense if it was defining a closure, but I'm not sure
what's in scope at all. How do I get hold of maven.gen.docs from in there?
Cheers, and all the best for Christmas and New Year,
Baz
Re: OT: codebase design guidelines - Happy Holidays!
Posted by Ben Walding <be...@walding.com>.
I don't believe this is off topic :) (and if it is, just say "But it's
Christmas!!!")
Maven Layout:
You'll want to have a look at :
http://jakarta.apache.org/turbine/maven/reference/dirlayout.html
Which shows the current practice for laying out Maven so that you don't
have to redefine a whole lot of properties.
Testing:
I tend to make blanket statements like
Unit Testing
All new code that could possibly fail must have unit-tests. Admittedly
the coverage isn't 100% yet, but with each release, the Quilt / Clover
coverage results must not decrease.
Coverage Testing
The minimum coverage (generate using |maven clean clover:html-report|)
for any non-trivial class within DataForge is 80%. A trivial class is
something which has no methods that would reasonably fail; eg. a bean
with no behaviour except getters and setters. Ideally the level would be
100%, but given that there are only so many monkey hours in a day, 80%
is the easy part.
John Casey wrote:
>I just thought I'd toss something out for a little light reading this
>holiday season. I'm trying to compile all that I've learned over the
>past few years on the nitty-gritty side of project management - codebase
>management. What I'm trying to nail down is the "correct" way to design
>a project so that it is manageable, usable to new developers, plugs into
>continuous integration tools, etc...
>
>Anyway, if you have time, I'd love any feedback I can get.
>
>http://www.commonjava.org/strategy.html
>
>I already know that I've forgotten to include a section on testing...I'm
>working on that.
>
>Cheers,
>John
>
>--
>To unsubscribe, e-mail: <ma...@jakarta.apache.org>
>For additional commands, e-mail: <ma...@jakarta.apache.org>
>
>
>
>
Re: OT: codebase design guidelines - Happy Holidays!
Posted by John Casey <jd...@00java.com>.
This is great! Thanks for the feedback, this is exactly what I needed.
BTW, is there a good book, or place I can go to read more discussion
like this?
Thanks again,
John
On Tue, 2002-12-24 at 05:43, Brian Ewins wrote:
> Interesting doc. I've got some specific and general comments; most of
> the specific bits could be summed up by 'rules have exceptions', though.
>
> "# all classes must follow a premeditated package dependency strategy
> * strategy shall be enforced by the build process"
>
> A good way to do this is to build things which are meant to be
> independent as separate jars. Probably not coincidentally, in my
> experience maven lends itself best to smaller jars, and then building
> the main project from these subproject jars.
>
> "code-internal constants ... shall always be declared in
> typesafe-enumeration style classes"
>
> well you do know there are issues with deserialization of typesafe
> enums? ( deser(ser(A))!=A )
>
> "all XML messages and parsers shall use an appropriate XML Schema
> document for conformance validation"
>
> Well that rules out maven.xml then ;). Seriously, there are a lot of
> situations where schemas are a Bad Thing, and even when you do have
> schema, there's the whole WXS/RELAX-NG argument over whether strict
> typing is always a good thing. (see the xml-deviant columns on xml.com
> for the arguments).
>
> "# filter sets...to enable reuse...separated by target system configuration"
>
> This is a 'build smell'. You're describing a process to support separate
> builds per target system. How are you testing all of these builds?
>
> To scale up delivery to many, many target systems, you need to have
> builds which are configured after they are installed, not while they are
> being built. This means that the build on all installations is exactly
> the same one you tested. It also helps you plan to stop configuration
> changes made onsite from being overwritten during an upgrade.
>
> "intermediate results of build steps shall be stored within a directory
> structure under /work"
>
> How do you distinguish 'intermediate' from 'final' results? You describe
> 'target/classes', when the classes are usually intermediate to building
> the jar. Don't ask people to distinguish the indistinguishable. To
> answer my own question - project deliverables are the only things you
> make which are clearly distinguishable from the intermediates (usually a
> jar, war, zip, or installer). Those /are/ things you should separate out.
>
> "a file called base-project.xml..."
>
> This guideline only makes sense if you've already written a build script
> that works this way - and I'll bet that it won't be the last word in
> project structures. So this more properly belongs in a set of
> instructions for using your specific build system, and the indefinite
> article shouldn't be used: "The file called base-project.xml ....".
> Theres several other bits like this in your doc; I think these confuse
> the requirements (good code management) with the implementation (a
> specific build process). This stuff all needs documented, but separately.
>
> "no code formatting specification shall be enforced..."
>
> Eh no, this is a nightmare when working in teams. Its also a bit silly
> when we have tools like jalopy available, but I do agree that simply
> reporting a lot of minor style errors with tools is not greatly helpful.
> Take a look at one of my bug reports on maven:
> http://jira.werken.com/secure/ViewIssue.jspa?key=MAVEN-159
>
> this gives you a style for checkstyle that won't report errors on
> anything jalopy can automatically fix. Its then up to you to use jalopy
> to keep things legible.
>
> More generally: when writing coding/design guidelines in the past I've
> found it helpful to distinguish:
> 1. things that a tool can fix
> 2. things that a tool can check
> 3. things that a human can check
> 4. things that can't be checked.
>
> Try to move everything in your guidelines as far up this chain as
> possible. Document (1) and (2) separately, make the tools part of your
> process, and don't expect people to remember all the rules; they won't,
> but the tool will point out when they break them. (3) forms your main
> guidelines document, because its the only one where you rely on people
> to actually remember and check things. So keep it separate and short,
> there's more chance people will be able to remember it all[1]. (4) is a
> list of all the things you need to think through better before you ask
> people to do them ;)
>
> I commented at the start that rules are made to be broken. It is ok to
> write rules which you will allow to be broken as long as you provide an
> extra rule for this:
> - Any of these rules may be broken if there is a justifiable reason to
> do so. The reason must be documented (if the breach is in code, as a
> comment).
>
> Finally, always provide blank/sample/template projects so its easy for
> devs to start out in the right direction.
>
> Cheers,
> Baz
> (Merry Christmas!)
>
> [1] For example, in one of my employers we had the Ellemtell C++
> guidelines (80+ pages?), Java guidelines intended to be slimmer than the
> C++ ones (Sun's plus our own; 35 pages IIRC), and perl guidelines
> written along the lines described above. The bit you had to remember was
> 2 pages long. Guess which guidelines got followed :)
>
> John Casey wrote:
> > I just thought I'd toss something out for a little light reading this
> > holiday season. I'm trying to compile all that I've learned over the
> > past few years on the nitty-gritty side of project management - codebase
> > management. What I'm trying to nail down is the "correct" way to design
> > a project so that it is manageable, usable to new developers, plugs into
> > continuous integration tools, etc...
> >
> > Anyway, if you have time, I'd love any feedback I can get.
> >
> > http://www.commonjava.org/strategy.html
> >
> > I already know that I've forgotten to include a section on testing...I'm
> > working on that.
> >
> > Cheers,
> > John
> >
> > --
> > To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> > For additional commands, e-mail: <ma...@jakarta.apache.org>
> >
> >
>
>
> --
> To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>
>
Re: OT: codebase design guidelines - Happy Holidays!
Posted by Henri Yandell <ba...@generationjava.com>.
On 1 Jan 2003, John Casey wrote:
> >"code-internal constants ... shall always be declared in
> >typesafe-enumeration style classes"
> >
> >well you do know there are issues with deserialization of typesafe
> >enums? ( deser(ser(A))!=A )
>
> Well, actually, simply writing the following snippet will solve that
> problem...
>
> private Object readResolve(){
> return lookupConstant(internalIndex);
> }
>
> where lookupConstant() is an internal private method which finds the
> appropriate constant instance based on an internal index in an internal
> array of the constants.
Extend the Enum class in Commons.Lang to avoid having to think about this.
Even with the readResolve fix, there are still issues with multiple
class-loaders I believe.
Hen
Re: OT: codebase design guidelines - Happy Holidays!
Posted by John Casey <jd...@00java.com>.
>"code-internal constants ... shall always be declared in
>typesafe-enumeration style classes"
>
>well you do know there are issues with deserialization of typesafe
>enums? ( deser(ser(A))!=A )
Well, actually, simply writing the following snippet will solve that
problem...
private Object readResolve(){
return lookupConstant(internalIndex);
}
where lookupConstant() is an internal private method which finds the
appropriate constant instance based on an internal index in an internal
array of the constants.
Regards,
John
Re: OT: codebase design guidelines - Happy Holidays!
Posted by Brian Ewins <Br...@btinternet.com>.
Interesting doc. I've got some specific and general comments; most of
the specific bits could be summed up by 'rules have exceptions', though.
"# all classes must follow a premeditated package dependency strategy
* strategy shall be enforced by the build process"
A good way to do this is to build things which are meant to be
independent as separate jars. Probably not coincidentally, in my
experience maven lends itself best to smaller jars, and then building
the main project from these subproject jars.
"code-internal constants ... shall always be declared in
typesafe-enumeration style classes"
well you do know there are issues with deserialization of typesafe
enums? ( deser(ser(A))!=A )
"all XML messages and parsers shall use an appropriate XML Schema
document for conformance validation"
Well that rules out maven.xml then ;). Seriously, there are a lot of
situations where schemas are a Bad Thing, and even when you do have
schema, there's the whole WXS/RELAX-NG argument over whether strict
typing is always a good thing. (see the xml-deviant columns on xml.com
for the arguments).
"# filter sets...to enable reuse...separated by target system configuration"
This is a 'build smell'. You're describing a process to support separate
builds per target system. How are you testing all of these builds?
To scale up delivery to many, many target systems, you need to have
builds which are configured after they are installed, not while they are
being built. This means that the build on all installations is exactly
the same one you tested. It also helps you plan to stop configuration
changes made onsite from being overwritten during an upgrade.
"intermediate results of build steps shall be stored within a directory
structure under /work"
How do you distinguish 'intermediate' from 'final' results? You describe
'target/classes', when the classes are usually intermediate to building
the jar. Don't ask people to distinguish the indistinguishable. To
answer my own question - project deliverables are the only things you
make which are clearly distinguishable from the intermediates (usually a
jar, war, zip, or installer). Those /are/ things you should separate out.
"a file called base-project.xml..."
This guideline only makes sense if you've already written a build script
that works this way - and I'll bet that it won't be the last word in
project structures. So this more properly belongs in a set of
instructions for using your specific build system, and the indefinite
article shouldn't be used: "The file called base-project.xml ....".
Theres several other bits like this in your doc; I think these confuse
the requirements (good code management) with the implementation (a
specific build process). This stuff all needs documented, but separately.
"no code formatting specification shall be enforced..."
Eh no, this is a nightmare when working in teams. Its also a bit silly
when we have tools like jalopy available, but I do agree that simply
reporting a lot of minor style errors with tools is not greatly helpful.
Take a look at one of my bug reports on maven:
http://jira.werken.com/secure/ViewIssue.jspa?key=MAVEN-159
this gives you a style for checkstyle that won't report errors on
anything jalopy can automatically fix. Its then up to you to use jalopy
to keep things legible.
More generally: when writing coding/design guidelines in the past I've
found it helpful to distinguish:
1. things that a tool can fix
2. things that a tool can check
3. things that a human can check
4. things that can't be checked.
Try to move everything in your guidelines as far up this chain as
possible. Document (1) and (2) separately, make the tools part of your
process, and don't expect people to remember all the rules; they won't,
but the tool will point out when they break them. (3) forms your main
guidelines document, because its the only one where you rely on people
to actually remember and check things. So keep it separate and short,
there's more chance people will be able to remember it all[1]. (4) is a
list of all the things you need to think through better before you ask
people to do them ;)
I commented at the start that rules are made to be broken. It is ok to
write rules which you will allow to be broken as long as you provide an
extra rule for this:
- Any of these rules may be broken if there is a justifiable reason to
do so. The reason must be documented (if the breach is in code, as a
comment).
Finally, always provide blank/sample/template projects so its easy for
devs to start out in the right direction.
Cheers,
Baz
(Merry Christmas!)
[1] For example, in one of my employers we had the Ellemtell C++
guidelines (80+ pages?), Java guidelines intended to be slimmer than the
C++ ones (Sun's plus our own; 35 pages IIRC), and perl guidelines
written along the lines described above. The bit you had to remember was
2 pages long. Guess which guidelines got followed :)
John Casey wrote:
> I just thought I'd toss something out for a little light reading this
> holiday season. I'm trying to compile all that I've learned over the
> past few years on the nitty-gritty side of project management - codebase
> management. What I'm trying to nail down is the "correct" way to design
> a project so that it is manageable, usable to new developers, plugs into
> continuous integration tools, etc...
>
> Anyway, if you have time, I'd love any feedback I can get.
>
> http://www.commonjava.org/strategy.html
>
> I already know that I've forgotten to include a section on testing...I'm
> working on that.
>
> Cheers,
> John
>
> --
> To unsubscribe, e-mail: <ma...@jakarta.apache.org>
> For additional commands, e-mail: <ma...@jakarta.apache.org>
>
>
OT: codebase design guidelines - Happy Holidays!
Posted by John Casey <jd...@00java.com>.
I just thought I'd toss something out for a little light reading this
holiday season. I'm trying to compile all that I've learned over the
past few years on the nitty-gritty side of project management - codebase
management. What I'm trying to nail down is the "correct" way to design
a project so that it is manageable, usable to new developers, plugs into
continuous integration tools, etc...
Anyway, if you have time, I'd love any feedback I can get.
http://www.commonjava.org/strategy.html
I already know that I've forgotten to include a section on testing...I'm
working on that.
Cheers,
John