GeoTools change proposal¶

This procedure is used to propose a change to the GeoTools API. By necessity all API changes must be applied to trunk (although RnD experiments may of been carried out in a branch or unsupported module prior to being proposed).

So you want to make a Change¶

When to use this Procedure¶

This procedure is used at the start of your project; before deadlines are established to ensure that the work you need to accomplish can be done and delivered.

When not to use this Procedure¶

This procedure is focused on API changes to the core library, for work limited to a plugin you should just be able to sort things out with the module maintainer.

Repeat - this procedure is for changes to public interfaces, for simple bug fixes and mistakes chat the the module maintainer.

Playing nicely with others¶

This procedure is used to let us work in a controlled and managed fashion:

preserve library stability
allow evolution
forbid controversial changes
up to date documentation

When will this procedure be revised¶

We have the following measures of success:

We want trunk to be directly used by GeoServer and uDig projects

If this no longer occurs we will revisit this policy
We want the user documentation to reflect trunk

If a release is delayed waiting for documentation we will need to revisit this policy
Client code will have a full release cycle to change over from deprecated code

This is not always possible when the interface is not defined by the GeoTools project (JTS and apache commons etc…)
Release update instructions should be exacting

Check List¶

Check	Task	Notes
x	Issue	The Jira issue will be used to record on going discussion
x	Proposal	This page reflects the current proposal
x	Email	Seek public feedback
x	Voting	Change is discussed and/or approved
x	Update	Introduce API change
x	Deprecate	Any prior art can be deprecated at this time
x	Documentation	Update documentation and examples
x	Release	API change must be included in a point release
x	Remove	Deprecated API can be removed after point release

Issue¶

You will need to create a new Jira issue to track discussion; this issue will eventually be marked as closed against a formal release and be accessible to users.

By using Jira we get a nice record for our release notes.

Proposal¶

The proposal page is used to track the current state of the proposal; it will be modified as discussions and compromises are reached.

Open up Proposals
Select Add Content and then Add Page
Click on Select a page template and select Proposal
Press Next>> and fill in the blanks

The resulting document is yours to play with - here is what you get out of the box:

Motivation: Quick description of what is needed
Contact: Use your [~confluence_profile] or email address
Tracker: Link to your Jira Issue
Tagline: Have some fun
Description: Contains as much background material as you need to convey the problem; and towards the end of the process enough design material to describe the solution
Status: Initially “under under construction”, eventually we will move on to “approved” and “completed in GeoTools 2.5.0”. There is also a quick task list to mark where you are stuck.
Resources: List of child pages and attachments; often used for diagrams and documents
Tasks: a rough outline of the plan, we are looking to make sure that volunteer time exists to solve the problem (rather then just started). Remember half a solution just looks like another problem.
API Changes: simple BEFORE and AFTER, this will be used in the update instructions associated with each release
Documentation Changes: Identify the developer and user documentation that needs to be modified as part of this proposal

The amount of detail you need depends on what you are up to:

Changes effecting multiple modules is significant and will need most of the above
Changes localised in the public API of a single module may be able to get by with only API changes and documentation updates

Email¶

Once you have the proposal page in place, and the Jira issue ready to capture discussion it is time to send an email.:

From: jgarnett@refractions.net
To: ~geotools-devel@lists.sourceforge.net
Subject: FunctionImpl Library separation

Justin found a short coming in our implementation of Functions; right
now we are focused on Implementation to the point we forgot to capture
the "idea" of a function.

Significantly if we do not have an implementation for a particular
function we cannot even represent that Expression in GeoTools.

This will require the introduction of a new API; and thus I am following
the GeoTools change proposal process and emailing the list.

Here are the links:

- https://osgeo-org.atlassian.net/projects/GEOT-1083
- https://github.com/geotools/geotools/wiki/Describe-Function-with-FunctionName

This change requires the introduction of *new* API (namely Library), and
will require the deprecation of our existing FunctionFactory extension
mechanism (as it is flawed). We can however "run with both" (i.e. duplicate,
deprecate, replace).

Cheers,
Jody Garnett

Voting¶

PMC members do vote on the change proposal, with the following votes:

+1	For
+0	Mildly for, but mostly indifferent
-0	Mildly against, but mostly indifferent
-1	Against - required to have an alternate suggestion

To avoid stagnation by lack of interest/time from community members the following assurances are provided:

svn access for changes is granted within 3 days from the proposal
proposal is accepted ‘automatically’ within 15 days (unless objections are raised)

Since I am sure your change is interesting enough here is what you need to proceed:

A successful proposal with no negative -1 votes
You can consider the the alternatives provided with the -1 votes and revise your proposal

It is also strongly recommended that you have:

Approval from the module maintainer for the API you are changing, if they have a grand vision it is good to go along with it
A lack of panic from effected module maintainers

Update¶

You will need to update GeoTools to make the new API available, creating new classes adding new methods as needed.:

interface Library {
   FilterCapabilities getFilterCapabilities();
   Object evaluate( String name, List params );
}

Please understand that adding methods to an interface is not always an option (since client code will be forced to update right away). You can create an additional interface with the required methods (and give users one release cycle to implement this additional API).

Deprecate¶

The next step is to deprecate the API being replaced (in the case of new API this step can be skipped).:

/** @deprecated Please use Library as a replacement */
interface FunctionFactory {
   ..
}

You (of course) must provide a replacement for deprecated API, it could be as simple as a workaround provided as part of the documentation.

Documentation¶

You will need to update all test cases and demo code to use the new API; since our test cases are often used by those learning the library this is especially important (also leaving deprecated code in the test cases assures us of a broken build one release cycle later when the plug is pulled).

The User Guide, and User Manual are often the target of documentation updates. The developers guide tries to stick to library architecture and only needs updating if you are changing the scope and/or focus of one of the core modules.

Release¶

The next step is to make the changed API available in at least a milestone release. It is good to ensure that an API change is in releasable state (this may pick up PMD failures or QA coverage needs that were missed earlier).

Remove¶

After the API change is included in a point release the deprecated code can be removed from trunk.

GeoTools

OSGeo