I will opine a bit based on what I have personally done historically on Commons projects, plus some thoughts on what we're currently doing in Shale[1] that might prove to be of interest (and/or a source of ideas on how to do it).
On 1/2/07, Dennis Lundberg <[EMAIL PROTECTED]> wrote:
Hi I've been looking at creating distributions for commons logging using Maven 2. So I did some reading on ASF policy regarding distributions and poked around in different commons components, to see if I could find a least common denominator. Unfortunately I haven't. So I've got a couple of questions for you to think about: 1. What should a source distribution include?
IMHO, a "source distribution" should always include all the files necessary to build the corresponding binary distribution with the project's favorite build tool. For an Ant based project, that meant having a build.xml file in the top level, plus a way to define and/or get the dependencies, plus all the sources in a hierarchy that the build.xml expects. For a Maven2 based project, it's a similar deal ... a pom.xml at the top, and all the sources in the right structure, so that the user could unpack the distro, run "mvn install" at the top level, and get the same results as what they'd get with the binary distro. 2. What should a binary distribution include?
From a standalone "distro" perspective, I would expect to see the binary
jars of the project itself, binary jars of dependencies (assuming license compatibility), and the javadocs. However, my current preferred practice (and what we are now doing with Shale) is to combine the source and binary distributions into a single "distro" that includes all of the above. In a Maven2 based world, you also need to consider the act of publishing into the Maven2 repository to be a "distribution" as well. In that case, you're generally including just POMs and JARs, but you have to deal with checksums and signatures on these artifacts as well. Reading the documentation for the assembly-plugin [1] for Maven 2 I
found an interesting feature that will come in the next version. It will create an assembly (distribution) of "the entire source project, including the Maven POM and other files outside of your source directory structure, but excluding all SCM files and the target directory" and archives for it (tar.gz, tar.bz2 and zip). Now this sound to me like the ideal source distro. A complete checkout. Then it's up to the user to build, read or do whatever he or she feels like with it.
Shale uses a custom assembly for the "framework" (which includes a master module and a bunch of submodules), and a custom assembly for each sample webapp, that conform to the "combined" philosophy described above. For a class library like most from Commons, it's pretty simple to set up something similar. Who downloads a binary distribution, why and what for? Someone who
doesn't use Maven to build their products. Because the don't want to, or don't know how to, build the commons component their selves. Because someone did all the building and assembling for them, i.e. they are lazy as in good lazy. So that's a broad audience we've got there.
Even on my Maven projects, I also download binary distros when I need the Javadocs and they weren't published into the repository. Same for the source distro if I need to debug. What do they need? Well in the case of commons they want the jar of
course. What else? Some documentation on how to use it, list of dependencies and such. The ASF also has needs when it comes to licensing. We need to put a LICENSE and NOTICE file in there.
"In there" actually means a couple of things for a Commons project -- in the distribution artifact itself (.zip or .tar.gz or whatever), *and* inside the library JAR's META-INF directory. What are your thoughts on this subject?
[1] http://maven.apache.org/plugins/maven-assembly-plugin/descriptor-refs.html -- Dennis Lundberg
Craig [1] http://shale.apache.org/
