Change proposal process

GeoFence change proposal

This procedure is used to propose a change to the GeoFence Project. By necessity all API changes must be applied to master(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 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 the user documentation to reflect master

  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 GeoFence project (Geotools, apache commons etc...)

• Release update instructions should be exacting

Check List

Check	Task	Notes
x	Issue	The 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 issue to track discussion; this issue will eventually be marked as closed against a formal release and be accessible to users.

Proposal

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:

• Motivation: Quick description of what is needed
• Contact: Use your avatar or email address
• Tracker: Link to your 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 construction", eventually we will move on to "approved" and "completed in GeoFence 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 issue ready to capture discussion it is time to send an email.:

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

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

Here are the links:
- xxxx
- xxxx

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

Geofence committers (for the moment we do not have a PMC) 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:

• git 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 GeoFence 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 master.