Hi,
Some comments inline.
Joakim Erdfelt wrote:
The maven release process criticism from Dan Kulp spawned an impromptu
ApacheCon gathering of the minds (Dan Kulp, Wendy Smoak, Jason Van Zyl,
and Myself) to define a better release process for maven.
We covered the needs of Apache with regards to ....
* Apache Top Level Poms (and Incubator requirements)
* LICENSE file and headers.
* NOTICES.txt file requirements.
* DISCLAIMER.txt file requirements (for incubator projects)
* The current release plugin.
* The desired release process.
* The need for a staging / acceptance of a release.
I'll try to cover all of these topics in as much detail as I can provide
in this email.
===============================================================================
== APACHE POMS
The incubator has requested a new incubator pom be created that extends
off of the apache.pom
So we'll wind up with a structure like this ...
+--------------+
| apache.pom |
+--------------+
\
+------------------------+
| apache-incubator.pom |
+------------------------+
\
+------------------+
| apache-tuscany |
+------------------+
Looks good. This should be generalized in the way that each ASF top level
project has a pom extending the apache pom.
===============================================================================
== LICENSE FILE / HEADER
The LICENSE file is a unique monster in the world of apache.
It will always be Apache v2.0.
It needs to be in the top level of all assemblies.
Is it allowed to customize the location of the license files?
Right now assemblies are just a directory archive (in the style
of /usr/local/app/[bin|lib|etc...]. There are also assemblies
that contain an installer application; Should the license file
be in both the unpacked installer archive and in the directory structure
created by the installer?
Also, for native binary distributions (much like .deb/.rpm), applications
might be installed (in the future) in /usr/[bin|lib|...]. That would mean the
license file
is placed in /usr/.
Some applications that 3rd party libs with mixed licences often create
a 'legal' or 'licences' directory, or place all licenses in the lib/ dir.
I know this doesn't occur with Apache distributions, but maybe we need to keep
support for this in mind for maven users.
It needs to be in the META-INF/ directory of all jar files.
It needs to be managed at a top level pom (not all sub modules).
So I propose that we create a new top level apache pom.
It will define the Apache v2.0 LICENSE file with the following contents.
[snip ASLv2]
This file will be the basis for a new maven-license-plugin which
provides the following functionality.
Just a note: we might want to merge with the CopyLegalFiles mojo
from Geronimo Genesis:
https://svn.apache.org/repos/asf/geronimo/genesis/trunk/plugins/tools-maven-plugin/src/main/java/org/apache/geronimo/genesis/plugins/tools
* license:inject
This is a manual goal of the license plugin to allow smart injection
of the LICENSE contents into
various files (with proper comments added).
Currently identified file types.
*.java, *.xml, *.properties, *.jsp
* license:check
Using the same filetype list as license:inject, this will create a
build-time failure if the
license does not exist in one or more files in your project tree.
[side note: I've always disliked the licences in source files. They get lost
anyway
in the binary/compiled form; they clutter svn; the root of the project already
defines a license that applies for all files within that directory structure.
But
the legal people probably have good reason to require this :)]
There will also be a maven-shared-license project created to house some
of the common license file manipulation routines so that
maven-checkstyle-plugin and maven-project-info-reports-plugin can
benefit from this effort also.
The top level Apache pom will have a <dependencyManagement> section
defined for jar/war plugin to
inject the LICENSE file into the META-INF/ locations.
The assembly plugin needs to have the ability to have pom managed
content (that supplements the assembly descriptor) be injected into the
output assembly too. This change will allow the LICENSE file to be
placed in the top level of the assemblies created.
The top level apache.pom will also define the -sources.jar and
-javadoc.jar creation with appropriate LICENSE file injection as well.
In this case they'll be in the root of the archive, not in the /META-INF, right?
===============================================================================
== NOTICES.txt and DISCLAIMER.txt
These files are standardized, and need to be injected into the META-INF/
directory of all jar files.
The top level apache.pom should utilize the changes made for LICENSE to
facilitate the needs of these files too.
The work done against the assembly plugin to allow for the LICENSE file
to be injected based off of a pom configuration (not an assembly
descriptor) will be used for the NOTICES.txt and DISCLAIMER.txt files too.
===============================================================================
== RELEASE PROCESS
The release process we settled on consists of 3 phases (4 goals)
release:prepare (goal / phase)
release:propose (goal / phase)
release:accept (goal / phase)
release:clean (goal)
Example of process, using fictious product.
Project Name: KungFoo
Version in TRUNK: 1.5-SNAPSHOT
Desired Release Version: 1.5
release:prepare
1) Create a branch off of TRUNK for the release.
BRANCH/1.5 now exists.
2) Update pom versions in BRANCH/1.5 to reflect version "1.5"
3) Commit pom changes into SCM.
4) Update pom versions in TRUNK to be the new development version
"1.6-SNAPSHOT"
5) Commit pom changes into SCM.
Current State:
TRUNK : 1.6-SNAPSHOT
BRANCH/1.5 : 1.5
Binary : n/a
release:propose
1) Kick off full build.
Compiles and installs (into local repo) all of the artifacts.
Executes the reports.
Inject the SCM revision into a pom/properties for future reference.
Include the SCM revision # or buildnumber in the artifact name.
Creates...
KungFoo-1.5.jar
KungFoo-1.5-sources.jar
KungFoo-1.5-javadoc.jar
KungFoo-1.5-bin.tar.gz
KungFoo-1.5-bin.tar.bz2
KungFoo-1.5-bin.zip
2) PGP Sign all of the binaries.
Results...
KungFoo-1.5.jar.asc
KungFoo-1.5-sources.jar.asc
KungFoo-1.5-javadoc.jar.asc
KungFoo-1.5-bin.tar.gz.asc
KungFoo-1.5-bin.tar.bz2.asc
KungFoo-1.5-bin.zip.asc
3) Deploy all binaries, sha1, md5, asc files to staging repository.
For apache, this will be likely be in
https://people.apache.org/build-staging-repository/
(NOTE: This repository does not exist yet)
4) Announce to dev mailing-list the proposed release.
Current State:
TRUNK : 1.6-SNAPSHOT
BRANCH/1.5 : 1.5
Binary : In staging directory.
release:accept
1) Create TAG/1.5 off of BRANCH/1.5
2) Copy all binaries for KungFoo-1.5 from staging to release
repository (central).
3) Verify PGP signature of binaries in remote release repository.
4) Deploy the site.
release:clean
1) Remove KungFoo-1.5 binaries from the staging repository.
Hm. This only describes a major release.
I think that branches should be created off tags, and that a developer should
do that, not a release plugin.
The above process looks ok for major releases (with reservations), but we
probably don't want to create
a branch for each bugfix release.
Say you're working on maven-2.0.x branch, currently at 2.0.5-SNAPSHOT. If we
follow the above
process, assuming that 'TRUNK' can also mean 'branch', we'd get a branch for
2.0.5,
which will never change since there are no 2.0.5.x releases. You have to stop
this recursion
somewhere - otherwise you'd get 2.0.5.1.1.1.1 branches.
Personally I like the following process when doing a bugfix release:
1) release:prepare: tag branch 2.0.x as 2.0.5-rc1
2) release:propose: stage 2.0.5-rc1
3) if there are -1's on the proposed release, work on 2.0.x branch (still at
2.0.5-SNAPHSHOT) and
release 2.0.5-rc2, -rc3 etc, until the release is ACK'd. (so basically: work
on the code, goto step 1,
incrementing the rcX counter).
4) release:accept: tag 2.0.5-rcX (which should be the same as the branch) as
2.0.5, build tag 2.0.5 and deploy to the live site.
Also update the 2.0.x branch's pom to 2.0.6-SNAPSHOT.
5) For a bugfix release: that's it. For a major release (say 2.1), also copy
the 2.1 tag to a 2.1.x branch.
(the pom's version in trunk will have been updated to 2.2-SNAPSHOT in step 4).
Comments?
-- Kenney
Hope this helps start the flow of discussion...
- Joakim Erdfelt
Daniel Kulp wrote:
Jason and I have had some chats about this, but I thought it might be good
to bring this up to a wider audience...
With more and more Apache projects (specifically incubator projects) using
maven, there are a lot more people that are running into "issues" related
to the apache requirements that are imposed on the build/release
processes. IMO, Maven itself should act as the "ideal model" for how to
do those things. Thus, when a question comes up, we can point to maven
and say "look how they are doing it." So the first question is: does
that make sense?
The problem is, Maven doesn't seem to do things "correctly", or at least
makes things hard(er) to do correctly.
1) The LICENSE/NOTICE files in the META-INF dir of the jar - currently,
none of the maven plugins do this at all. I've seen projects handle
this in a couple different ways. Some projects put them in the
src/main/resources... dir like other resources, but that kind of hides
them. Others put them in the same dir as the pom.xml and add a "."
resource dir, but that breaks eclipse:eclipse. Both have the issue
of having BUNCHES of copies of the LICENSE and NOTICE files to maintain,
which sucks.
There are a couple options. One option that I understand is coming in
2.1 is the ability to access stuff from the "parent" directory. Shared
resources type things. Thus, a single copy could be used.
Honestly, I'd like to see a "Apache-Maven" plugins (and a Incubator
subclass plugin) that would automatically add those files automatically
when possible.
One note: according to http://www.apache.org/legal/src-headers.html, all
Apache releases done AFTER November 1, 2006 must have the license/notice
files done correctly. Thus, this item really needs to be taken care of
REAL SOON NOW.
2) The release process - I honestly think Maven does this "wrong." At
least for incubator projects, we need to do the
tagging/build/signing/etc.. first, then vote on the resulting binaries.
This definitely doesn't seem to be what maven is doing. They seem to
vote on the "state of the code in the repository", then do the release
steps. I think it would be good if the processes that were used could
act as an example, especially for the incubator folks that are learning.
My (somewhat wacky idea) might be to add a "release:stage" that would do
ALL the release steps, but to a "staging area" (apache home directory or
similar, maybe need a "staging" section to the distributionManagement
section of the pom) that the project could vote on, then another release
goal to copy the staging to the real "release" area if/when the vote
passes.
3) Signing/deploying - this is another area that maven doesn't seem
to "help" too much. Everyone seems to run deploy/release, then login to
the people.apache.org and run a script over the directory to do the
signing. It would be nice to have "help" from maven to do that.
Actually, the Maven project doesn't seem to do it at all sometimes. The
javadoc plugin did get signed, but the new clover one did not. However,
the new maven-metadata.xml files got changed with javadoc, but didn't get
re-signed so the .asc file does not match and thus verify fails. Kind
of hard to "trust" the maven repository when the sigs fail.
Anyway, I just wanted to start a discussion. I'd love to point to maven
and say "model Apache maven project," but, IMO, there is a bit to go.
Enjoy!
---------------------------------------------------------------------
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]
