You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Brett Porter <br...@apache.org> on 2006/02/07 07:24:13 UTC
Parent vs dependency aggregation, including sites and reports
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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Parent vs dependency aggregation, including sites and reports
Posted by Carlos Sanchez <ca...@apache.org>.
I prefer aggregation vs inheritance.
What about deploying the sites to the repo as type "site" and then
from the aggregated site depend on them and make the aggregated site?
On 2/6/06, Brett Porter <br...@apache.org> 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: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Parent vs dependency aggregation, including sites and reports
Posted by John Casey <jd...@yahoo.com>.
I think this is a move in the right direction, in a more general sense.
It's time we thought of dependencies in a more abstract way, I think.
Rather than talking about them as purely code dependencies, I think it's
important to think of them as things that the project needs in order to
build, whatever that means.
When we start talking about documentation-only projects, the concept of
a dependency must naturally change too. Likewise when we're talking
about an EAR dependency, as there might be several kinds of dependencies
that each may require some handling beyond simply (a) throwing them on a
given classpath, and (b) including them wholesale in a directory when
the assembly is created. But, back to the documentation discussion...
Using inheritance to "roll up" documentation from child projects does
overload the meaning of the modules section, and causes a problem in the
processing of the build as a whole. When are we processing the parent
POM before the child modules? When are we processing the modules first?
When do we have to perform some operation on the parent POM before *and*
after? Using a dependency hierarchy within the build would straighten
this out, it seems, since you will have direct access to the project
artifact and all its attachments of all of your dependency projects by
simply using ${project.artifactMap}.
Finally, to reiterate, this new method will be a more accurate
representation of the dependency hierarchy. Parents don't depend on
children, and a dependency relationship does not always mean a code
dependency.
Hope that helps muddy things up a bit. ;-)
-john
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: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: Parent vs dependency aggregation, including sites and reports
Posted by Brett Porter <br...@apache.org>.
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: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org