Return-Path: 
 <solr-dev-return-1614-apmail-lucene-solr-dev-archive=lucene.apache.org@lucene.apache.org>
Delivered-To: apmail-lucene-solr-dev-archive@locus.apache.org
Received: (qmail 69735 invoked from network); 2 Dec 2006 01:41:03 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2)
  by minotaur.apache.org with SMTP; 2 Dec 2006 01:41:03 -0000
Received: (qmail 6078 invoked by uid 500); 2 Dec 2006 01:41:12 -0000
Delivered-To: apmail-lucene-solr-dev-archive@lucene.apache.org
Received: (qmail 6046 invoked by uid 500); 2 Dec 2006 01:41:11 -0000
Mailing-List: contact solr-dev-help@lucene.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:solr-dev-help@lucene.apache.org>
List-Unsubscribe: <mailto:solr-dev-unsubscribe@lucene.apache.org>
List-Post: <mailto:solr-dev@lucene.apache.org>
List-Id: <solr-dev.lucene.apache.org>
Reply-To: solr-dev@lucene.apache.org
Delivered-To: mailing list solr-dev@lucene.apache.org
Received: (qmail 6036 invoked by uid 99); 2 Dec 2006 01:41:11 -0000
Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133)
    by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 01 Dec 2006 17:41:11 -0800
X-ASF-Spam-Status: No, hits=0.0 required=10.0
	tests=
X-Spam-Check-By: apache.org
Received-SPF: error (herse.apache.org: local policy)
Received: from [169.229.70.167] (HELO rescomp.berkeley.edu) (169.229.70.167)
    by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 01 Dec 2006 17:40:56 -0800
Received: by rescomp.berkeley.edu (Postfix, from userid 1007)
	id 6A2175B791; Fri,  1 Dec 2006 17:39:33 -0800 (PST)
Received: from localhost (localhost [127.0.0.1])
	by rescomp.berkeley.edu (Postfix) with ESMTP id 6653F7F403
	for <solr-dev@lucene.apache.org>; Fri,  1 Dec 2006 17:39:33 -0800 (PST)
Date: Fri, 1 Dec 2006 17:39:33 -0800 (PST)
From: Chris Hostetter <hossman_lucene@fucit.org>
To: Solr Dev <solr-dev@lucene.apache.org>
Subject: Re: release format
In-Reply-To: <Pine.LNX.4.58.0611282319490.28607@hal.rescomp.berkeley.edu>
Message-ID: <Pine.LNX.4.58.0612011702400.27676@hal.rescomp.berkeley.edu>
References: <c68e39170611282126t116c738ua88adf39625dae7d@mail.gmail.com>
 <Pine.LNX.4.58.0611282319490.28607@hal.rescomp.berkeley.edu>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
X-Virus-Checked: Checked by ClamAV on apache.org


Holy crap, I hate manifest files.

the good news is, I completely missunderstood the purpose of
"Mafivest-Version" (aparently so have most of the people out there
creating manifest files) .. it identifies the manifest file format version
... of which the only legal value ever defined is "1.0" .. great!

the bad news is that while the manifest file documentation says nothing
about "Specification-Version" other then "The value is a string that
defines the version of the extension specification." ... the various
javadocs make it very clear that it must be a dotted numeric value ... so
we're back to the same problem i started with.

i took a stab at the approach i outlined before, didnt' like it, so i took
a more direct route -- left ${version} alone to mean what it use to mean
(and what it means for other Lucene projects) and added a new
${specversion} which by default is build out of a hardcoded number and the
current date.  a full patch is below, but the key thing to notice is...

  <!-- Solr Implimentation Version -->
  <!--
       This can be any string value that does not include spaces
       This will be used when creating build artifact file names.

       By default, this should be set to "X.Y.Ndev" where X.Y.N is
       "1 greater" then the last version released (on this branch).
    -->
  <property name="version" value="1.0" />

  <!-- Solr Specification Version -->
  <!--
       This will be used in the Manifest file, and therefore must
       match the pattern "digit+{.digit+}*"

       By default, this should be set to "X.Y.M.${dateversion}"
       where X.Y.M is the last version released (on this branch).
    -->
  <property name="specversion" value="1.0.${dateversion}" />

  <!-- Incubation Artifact Disclaimer Suffix -->
  <!-- Once graduated from incubation, find/remove all refs to this prop -->
  <property name="incubation-suffix" value="-incubating" />

(note that i didn't acctually change the versions to reflect what they
theoretically should be, just left them "1.0" and documented them)

the idea being that it's time to make our irst official release, assuming
we call it "1.1.0" we use...

     ant -Dversion=1.1.0 -Dspecversion=1.1.0

...our artifacts have names like...

     apache-solr-1.1.0-incubating.*

...and our manifest has versions that look like...

     Specification-Version: 1.1.0
     Implementation-Version: 1.1.0-incubating - yonik - 2006-12-13 12:34:56

Durring our release, he version values baked into build.xml will be...

     version=1.1.1dev
     specversion=1.1.0.${dateversion}

...and anyone who runs "ant package" on the commandline after that will
get files named...

     apache-solr-1.1.1dev-incubating.*

...and the manifest file will have version entries like this...

     Specification-Version: 1.1.0.2006.12.31.23.59.59
     Implementation-Version: 1.1.1dev-incubating - joeblo - 2006-12-31 23:59:59

(the key there being that the specification version denotes that it's
something "after" spec version 1.1.0, and the impl version unique
identifies the artifact)

So ... what do you guys think?



Index: build.xml
===================================================================
--- build.xml	(revision 481446)
+++ build.xml	(working copy)
@@ -27,14 +27,37 @@
     <format property="year" pattern="yyyy"/>
     <format property="DSTAMP" pattern="yyyy-MM-dd"/>
     <format property="TSTAMP" pattern="HH:mm:ss"/>
+    <!-- datetime format that is safe to treat as part of a dotted version -->
+    <format property="dateversion" pattern="yyyy.MM.dd.HH.mm.ss" />
   </tstamp>

   <!-- Java Version we are compatible with -->
   <property name="java.compat.version" value="1.5" />

-  <!-- Solr version -->
+  <!-- Solr Implimentation Version -->
+  <!--
+       This can be any string value that does not include spaces
+       This will be used when creating build artifact file names.
+
+       By default, this should be set to "X.Y.Ndev" where X.Y.N is
+       "1 greater" then the last version released (on this branch).
+    -->
   <property name="version" value="1.0" />
+
+  <!-- Solr Specification Version -->
+  <!--
+       This will be used in the Manifest file, and therefore must
+       match the pattern "digit+{.digit+}*"
+
+       By default, this should be set to "X.Y.M.${dateversion}"
+       where X.Y.M is the last version released (on this branch).
+    -->
+  <property name="specversion" value="1.0.${dateversion}" />

+  <!-- Incubation Artifact Disclaimer Suffix -->
+  <!-- Once graduated from incubation, find/remove all refs to this prop -->
+  <property name="incubation-suffix" value="-incubating" />
+
   <!-- 3rd party libraries for compilation -->
   <property name="lib" value="lib" />

@@ -51,7 +74,7 @@
   <property name="example" value="example" />

   <property name="fullname" value="apache-${ant.project.name}"/>
-  <property name="fullnamever" value="apache-${ant.project.name}-${version}"/>
+  <property name="fullnamever" value="apache-${ant.project.name}-${version}${incubation-suffix}"/>

   <!-- Javadoc properties -->
   <property name="javadoc.years" value="2006 - ${year}" />
@@ -148,8 +171,8 @@
       use="true"
       encoding="utf8"
       access="${javadoc.access}"
-      windowtitle="${Name} ${version} API"
-      doctitle="${Name} ${version} API"
+      windowtitle="${Name} ${version}${incubation-suffix} API"
+      doctitle="${Name} ${version}${incubation-suffix} API (${specversion})"
       bottom="Copyright &amp;copy; ${javadoc.years} The Apache Software Foundation"
       >
         <packageset dir="${src}/java"/>
@@ -255,38 +278,44 @@
      <manifest mode="replace" file="${dest}/META-INF/MANIFEST.MF">
         <!--
         http://java.sun.com/j2se/1.5.0/docs/guide/jar/jar.html#JAR%20Manifest
-
-        Manifest-Version must be "digit+{.digit+}*"
-        ...so what do we want to do instead?
-        <attribute name="Manifest-Version" value="${version}"/>
+        http://java.sun.com/j2se/1.5.0/docs/guide/versioning/spec/versioning2.html
+        http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Package.html
+        http://java.sun.com/j2se/1.5.0/docs/api/java/util/jar/package-summary.html
+        http://java.sun.com/developer/Books/javaprogramming/JAR/basics/manifest.html
         -->
-        <!-- don't included a 'Created-by' attribute, it's purpose is
+        <!-- Don't set 'Manifest-Version' it identifies the version of the
+             manifest file format, and should allways be 1.0 (the default)
+
+             Don't set 'Created-by' attribute, it's purpose is
              to identify the version of java used to build the jar,
-             which ant will do by default - but ant will happily
-             override with a bogus string if you tell it to
+             which ant will do by default.
+
+             Ant will happily override these with bogus strings if you
+             tell it to, so don't.
+
+             NOTE: we don't use section info because all of our manifest data
+             applies to the entire jar/war ... no package specific info.
           -->
-        <section name="org/apache/solr/">
-          <attribute name="Extension-Name"
-                     value="org.apache.solr"/>
-          <attribute name="Specification-Title"
-                     value="Apache Solr Search Server"/>
-          <!-- spec version can be any string -->
-          <attribute name="Specification-Version"
-                     value="${version}"/>
-          <attribute name="Specification-Vendor"
-                     value="The Apache Software Foundation"/>
-          <attribute name="Implementation-Title"
-                     value="org.apache.solr"/>
-          <!-- impl version can be any string -->
-          <attribute name="Implementation-Version"
-                     value="${version} - ${DSTAMP} ${TSTAMP}"/>
-          <attribute name="Implementation-Vendor"
-                     value="The Apache Software Foundation"/>
-          <attribute name="X-Compile-Source-JDK"
-                     value="${java.compat.version}"/>
-          <attribute name="X-Compile-Target-JDK"
-                     value="${java.compat.version}"/>
-        </section>
+        <attribute name="Extension-Name"
+                   value="org.apache.solr"/>
+        <attribute name="Specification-Title"
+                   value="Apache Solr Search Server"/>
+        <!-- spec version must match "digit+{.digit+}*" -->
+        <attribute name="Specification-Version"
+                   value="${specversion}"/>
+        <attribute name="Specification-Vendor"
+                   value="The Apache Software Foundation"/>
+        <attribute name="Implementation-Title"
+                   value="org.apache.solr"/>
+        <!-- impl version can be any string -->
+        <attribute name="Implementation-Version"
+                   value="${version}${incubation-suffix} - ${user.name} - ${DSTAMP} ${TSTAMP}"/>
+        <attribute name="Implementation-Vendor"
+                   value="The Apache Software Foundation"/>
+        <attribute name="X-Compile-Source-JDK"
+                   value="${java.compat.version}"/>
+        <attribute name="X-Compile-Target-JDK"
+                   value="${java.compat.version}"/>
      </manifest>
   </target>