I'm delighted to see these issues addressed. A few small comments below.
On 10/13/06, Joakim Erdfelt <[EMAIL PROTECTED]> 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 |
+------------------+
===============================================================================
== 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.
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) --
Copyright 2006 - The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied.
See the License for the specific language governing permissions and
limitations under the License.
--(snip)--
This file will be the basis for a new maven-license-plugin which
provides the following functionality.
* 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
Should have *.html files as well.
Ideally the set of file types (and strategies for license injection and
checking) would be extensible.
I assume one of the characteristics of "smart" will be dealing with the
copyright dates (if any)?
* 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.
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.
===============================================================================
== 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.
What (if any) effect do these targets have on produced websites? Or is that
still a completely separate process because different projects will want to
do different things?
Hope this helps start the flow of discussion...
- Joakim Erdfelt
Craig McClanahan
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]
