release format

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

release format

Yonik Seeley-2
On 11/28/06, Yonik Seeley <[hidden email]> wrote:
> src.zip isn't packaged as a release.
> Here is what I'm currently "testing":

Should be:

$ cat disttest

DIR=disttestdir
rm -rf $DIR
svn checkout http://svn.apache.org/repos/asf/incubator/solr/trunk $DIR
cd $DIR
ant package -Dversion=1.0-incubating
cd -
rm -rf apache-solr-1.0-incubating
tar xvzf $DIR/dist/apache-solr-1.0-incubating.tgz



-Yonik
Reply | Threaded
Open this post in threaded view
|

Re: release format

Chris Hostetter-3

: ant package -Dversion=1.0-incubating

...from what i've been reading about manifest files, we *have* to have
some sort of purely numeric version number (digit+{.digit+}*) in order to
have a compliant MANIFEST.MF

I would suggest we make it a policy for ${version} to be strictly numeric,
and do something like this...

  <tstamp>
    <format property="versiondate" pattern="yyyy.MM.dd"/>
  </tstamp>
  <!-- Dev/Nightly base version, set to value of last official release -->
  <!-- ...this property should only be used in defining ${version} -->
  <property name="version.base" value="1.0" />
  <!-- Numeric Solr version, override for official builds -->
  <property name="version" value="${baseversion}.${versiondate}" />
  <!-- full text version of Solr, eventually the same as ${version} -->
  <property name="longversion" value="${version}-incubating" />

...and replace all current usages of ${version} with ${longversion}




-Hoss

Reply | Threaded
Open this post in threaded view
|

Re: release format

Chris Hostetter-3

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>

Reply | Threaded
Open this post in threaded view
|

Re: release format

Chris Hostetter-3

: 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...

went ahead and commited this (albiet with version=1.1-dev since yonik
hcanged that already) and updated the HowToRelease wiki.


-Hoss