Ok, this was a bit hard to grasp in mail, so Jason, John and I went
through it on IRC a bit. Here are some things we arrived at. I'm being
deliberately verbose and breaking it down point by point. This is all
just best practice that we want to ensure the plugins can facilitate - I
think there a number of variations on this if you want to abuse the
available flexibility.
1) the aggregation point should be the root of the project.
The reason for this is that:
* it is more intuitive
* its more natural with the source code layout to pull in modules
(children in scm) rather than dependencies (siblings in scm)
* it makes aggregated reports easier to produce, as well as a better
default assembly.
* John pointed out it is entirely possible to manipulate the parent
project in eclipse by using a technique of creating eclipse links that
the eclipse plugin can already do.
2) the site generated from that project root, when deployed, forms the
"reference" part of a site and includes javadoc, reports, etc.
3) any content you want to include in the developer portal goes in a
site directory at the root. This should be minimised and possibly all
automatically generated.
4) documentation you intend to bundle with or version according to the
main release should be a site sub-module of the project (see
"documentation" below). This can inherit the navigation from the main
project instead of the parent project, so I need to determine if POM
inheritance is appropriate here, or if site inheritance should diverge
from pom inheritance.
5) navigational inheritance should reflect site structure in terms of
depth. Automatically generated menu items such as reports and modules
can't be inherited, so those menus would be folded up in the child
(which is normal).
6) documentation for developers might live as part of the root project,
part of the distributed documentation, or part of a new
developer-documentation module that operates like the documentation one
and may or may not be distributed. This is up to the person doing the build.
7) web site content unrelated to the release or the code is a separate
module like we have in maven now and is shown below. It is deployed
independently and probably more regularly.
The resulting directory structure (thanks to Jason for pointing out
"tree", which even exists on cygwin :)
.
|-- components
| `-- trunk
| |-- maven-artifact
| | `-- pom.xml
| |-- maven-core
| | `-- pom.xml
| |-- src
| | |-- main
| | | `-- assembly
| | | |-- bin.xml
| | | `-- src.xml
| | `-- site
| | |-- apt
| | | `-- index.apt
| | `-- site.xml
| |-- documentation
| | |-- src
| | | `-- site
| | | `-- apt
| | | `-- index.apt
| | `-- pom.xml
| `-- pom.xml
`-- site
|-- src
| `-- site
| `-- site.xml
`-- pom.xml
site --> http://maven.apache.org/
user-guide --> http://maven.apache.org/guides/
components --> http://maven.apache.org/reference/${project.version}/
I'll follow up with a reply to my other thread working this through in
practice for Maven.
any thoughts? disagreements?
- Brett
Brett Porter wrote:
> Hi folks,
>
> This is pretty important to start punting around as I need to lock in a
> best practice that works on Maven 2.0 and can be used in the site
> plug-in release. Please give this a review as soon as possible.
>
> I am battling the age old question where we have parent as inheritance
> and parent as a build aggregator. I'm still inclined to think that we
> should separate the functional from the informational (feedback on
> http://www.nabble.com/POM-Problems-and-Inheritence-t642303.html#a1708556
> still welcome!), we're stuck with the current situation for right now.
>
> Recently, we've been talking about making the parents produce aggregated
> content - assemblies, ears, aggregated site reports. This results in a
> src/ directory under the root that sits with the parent. I'd alluded to
> this in
> http://www.nabble.com/-discuss-change-to-parent-hierachy-t898697.html#a2329650
> which I'll revise based on any decision here.
>
> Chatting with Jason, we've agreed it doesn't quite feel right, though
> for my part I'm not convinced it's a bad thing yet but rather just
> something I'm not used to. The main downside I see remains the inability
> to do anything with it in Eclipse :)
>
> The alternative is to make everything a module of the parent, using
> dependencies to represent the things to aggregate. This removes the need
> to make <modules> act like dependencies and keeps the parent clean as an
> inheritance and build entry point. All the outputs of the build end up
> in a module.
>
> Practical example:
>
> maven/components/trunk/
> pom.xml
> maven-artifact/
> maven-core/
> ...
> maven-dist/
> maven-user-guide/
> maven-reference-guide/
>
> The new stuff here:
> - maven-user-guide is a site that contains documentation for Maven. It
> would have a lot of the stuff from the site now under /guides/, but is
> here to be versioned and distributed. It would be of type assembly and
> produce an zip of the docs for individual download.
>
> - maven-dist is of <packaging>assembly</packaging> and contains the
> assembly descriptors and binary files currently in maven-core. It would
> depend on maven-user-guide and bundle that in some binary distributions
> that include documentation (I generally prefer a separate bundle as
> above, but its an option as I'm thinking general practices here)
>
> - maven-reference-guide is a site that is deployed to include
> documentation for Maven developers. It depends on all the modules and
> while it doesn't produce a distribution, it provides the site that links
> in all the other modules and would produce any aggregate reports. The
> site plug-in would have to be able to include dependencies in a menu
> instead of modules, which might be a hassle as we are now reproducing a
> lot of information. This is the one I'm least comfortable about. Note
> that some of this content might be included in a user-guide (eg
> aggregated javadoc), so it needs to work there too.
>
> Any thoughts? It's obvious at this point the site inheritance needs a
> bit of rethought - most likely the site descriptor will need to have its
> own <parent> element for finding the parent site descriptor.
>
> Thanks,
> Brett
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
