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. 1. Open up Proposals 2. Select **Add Content** and then **Add Page** 3. Click on Select a page template and select Proposal 4. 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.