Skip GeoTools 3 - STEMLab/geotools GitHub Wiki

Contact: Jody Garnett
Tracker: https://osgeo-org.atlassian.net/browse/GEOT-3500
Tagline: GeoTools 8-SNAPSHOT

This proposal does not change our project project procedures or policy, it reflects confidence in our approach.

Description

The proposal is to skip GeoTools 3 (and the clean break with compatibility it represents) and go with
a numbering system that reflects our gradual API change (and maturity of the project).

This represents a strong commitment by the team that our development model is working and that we will
not need a ground up rewrite to move the library forward.

As a team we have:

GeoTools 2.1 Transitioned from FeatureStore to DataStore (with only the small bump of FeatureCollection which troubles us to this day)
GeoTools 2.3 Transitioned to immutable Filters
GeoTools 2.5 Transitioned to a new Feature Model and Java 5
We also have witnessed Justin's great work replacing the guts of GeoServer in 1.7 prior to GeoServer 2.0 making the changes visible to users

In short we are tough, confident, and careful of our user community.

Drop the 2

This entire project was started as GeoTools "2":

we have already dropped "2" from our website, our jars (they used to be gt2-main), .. so let us drop it from our version numbers as well.
This would align us with normal maven "major","minor","patch" numbering. This difference caught up a number
of users upgrading from 2.6.x to 2.7.x recently.
Consider it as a request to pull a Java 5 (JDK 1.5 was published as Java 5 for marketing reasons).

Version Numbers

Even though I said this proposal would not change our project procedures, the developers
guide does not currently reflect what we actually do.

The current developers guide page versioning is incorrect and reflects language prior to our decision to issue all GeoTools jars with the same verison number.

The following change reflects version numbers applying to the library as a whole:

GeoTools jars are versioned as a group with version numbers are based on 3 digits::

  <major>.<minor>.<patch>

* Major (first digit), is incremented to indicate that a module has lost full compatibility to earlier versions.

  So you can safely upgrade to later versions of a module so long as the major version has not changed.

* Minor (second digit) is incremented whenever new features are added.

  Modules are forward compatible across minor versions, but usually not backward compatible.

* Patch (last digit) is for bug fixes.

  It is used to indicate fixes in bugs only. No new features were made and full compatibility is preserved.

GeoTools jars released from trunk are versioned with version number based on 2 digits::

    <major>.<minor>-M<milestone>
    <major>.<minor>-RC<candidate>

* Milestone is used to mark alpha or beta releases as appropriate (example 8.0-M1)
* Release Candidates are marked 8.0-RC1 and indicate that the branch has been forked
  off trunk in preparation for final release.

In the distant past we considered allowing modules to keep their own version number; this threat was cause for confusion / concern / angst / and possibility for failure.

Release Examples

We can also offer the examples used in how to cut a release::

Example of branch names:

...
   First, change the default directory according the release to be performed:

   ================= =================================================
   GeoTools 8.x      http://svn.osgeo.org/geotools/trunk
   GeoTools 2.7.x    http://svn.osgeo.org/geotools/branches/2.7.x
   GeoTools 2.6.x    http://svn.osgeo.org/geotools/branches/2.6.x
   GeoTools 2.5.x    http://svn.osgeo.org/geotools/branches/2.5.x
   GeoTools 2.2.x    http://svn.osgeo.org/geotools/branches/2.2.x
   ================= =================================================

...

We would also use 8.x for the folder name in source forge (8.x sorts before 2.7.x so we are fine).

Example of svn commands:

2. Depending on the release you are performing choose the appropriate svn commands below.

   * Releasing a milestone from trunk:

     Creates the tag directly from the trunk::

       svn copy http://svn.osgeo.org/geotools/trunk
                http://svn.osgeo.org/geotools/tags/8.0-M2
                -m "Created 8.0-M2 tag from revision 33797." -r 33797

     The reason we are using -r 33797 is so we don't get tripped up by anyone who committed while
     between when we tested trunk and now.

   * Releasing first release candidate

     First creates the branch::

        svn copy http://svn.osgeo.org/geotools/trunk
                 http://svn.osgeo.org/geotools/branches/8.x
                 -m "Created 8.x branch from revision trunk 34232." -r 34232

     Then the tag::

        svn copy http://svn.osgeo.org/geotools/branches/8.x
                 http://svn.osgeo.org/geotools/tags/8.0-RC0
                 -m "Created 8.0-RC0 release candidate"

   * Releasing additional releases from a branch (release candidate, release or patch):

     Creates an additional release candidate from the branch::

       svn copy http://svn.osgeo.org/geotools/branches/8.x
                http://svn.osgeo.org/geotools/tags/8.0-RC1
                -m "Created 8.0-RC1 release candidate" -r 37232

     Creates a release::

       svn copy http://svn.osgeo.org/geotools/branches/8.x
                http://svn.osgeo.org/geotools/tags/8.0.0
                -m "Created 8.0.0 release" -r 37232

     Creates a patch release for bug fixes::

       svn copy http://svn.osgeo.org/geotools/branches/8.x
                http://svn.osgeo.org/geotools/tags/8.0.1
                -m "Created 8.0.1 patch release" -r 37232

     Creates a dot release for api or feature addition::

       svn copy http://svn.osgeo.org/geotools/branches/8.x
                http://svn.osgeo.org/geotools/tags/8.1.0
                -m "Created 8.1.0 patch release" -r 37232

   * The odd scenario out is creating a patch release from a previous tag after the branch
     has already moved on.

     This only occurs via customer request and is an unusual circumstance.

       svn copy http://svn.osgeo.org/geotools/tags/8.0.1
                http://svn.osgeo.org/geotools/tags/8.0.2
                -m "Created 8.0.2 patch release" -r 37232

     We would then expect the developer to apply the required fixes to this tag
     and issue a release.

       svn commit -m "Released 8.0.2 patch release" -r 37232

3. Verify that the tag has been correctly created by visiting the repository web page:

   *  http://svn.osgeo.org/geotools/tags/

Status

This proposal has been approved for 8.x.

Voting has not started yet:

Andrea Aime +1
Ben Caradoc-Davies: +1
Christian Mueller
Ian Turton +1
Justin Deoliveira +1 (wanted doc changes above)
Jody Garnett +1
Michael Bedward +0
Simone Giannecchini +0

Community feedback:

Joachim Van der Auwera +1

    | :white_check_mark: | :no_entry: | :warning:               | :negative_squared_cross_mark: |

------------|--------------------|------------|-------------------------|-------------------------------| no progress | done | impeded | lack mandate/funds/time | volunteer needed |

✅ Change to 8-SNAPSHOT
✅ Update the doc/build.xml so that the docs come out referring to 8-SNAPSHOT
✅ patch skip3.patch created
✅ Update the release instructions with standard maven Major / Minor / Patch numbering scheme
Update Jira roadmap
Update Wiki support pages for 8.x and 8 Downloads
Issue a blog post describing the change

API Changes

There is no api change.