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]