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).
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.
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.
This procedure is used to let us work in a controlled and managed fashion:
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 | Task | Notes |
|---|---|---|
| x | Issue | The Jira issue will be used to record on going discussion |
| x | Proposal | This page reflects the current proposal |
| x | 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 |
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.
The proposal page is used to track the current state of the proposal; it will be modified as discussions and compromises are reached.
The resulting document is yours to play with - here is what you get out of the box:
The amount of detail you need depends on what you are up to:
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:
- http://jira.codehaus.org/browse/GEOT-1083
- http://docs.codehaus.org/display/GEOTOOLS/FunctionImpl Library separation
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
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:
Since I am sure your change is interesting enough here is what you need to proceed:
It is also strongly recommended that you have:
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).
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.
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.
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).
After the API change is included in a point release the deprecated code can be removed from trunk.