Supporting your module

The GeoTools library plays host to several “unsupported” components, here is the process for formally including your work in the as a core part of the GeoTools library.

• Why Support your Module

  Benefits from having a supported module:

  • Module bundled up as part of the GeoTools release process and is available for download

  • Module JUnit test are run time to verify your module works and is not broken by changes

  • You can create Online-Tests for builder server to run

• Picking up a Module

  If you are interested in picking up an unsupported module (perhaps it was abandoned?) have a look into the section on Module Maintainers - you can volunteer as Module Maintainer if you interested.

Here is a check-list for module graduation:

Check	Step	Notes
x	Visibility	Communicate module status to users
x	Intellectual Property Check	Build user trust, OSGeo policy
x	Follow the Developers Guide	Project policies
x	User Documentation	Ensure work is accessible to users
x	Ask	Ask to be included in the next release

Visibility / Module Status

The GeoTools Gold Star Quality Assurance Check defines a couple of quick QA tests allowing you to rate your module according to the number of gold stars it has earned.

1. The first step is to rate your module:

   Gold Star Quality Assurance Check

2. GeoTools expects four stars for a supported module.

3. Create a README.md file:

   • show project status

   • show IP status

4. The goal here is to make your module status visible to end users.

   • Blog posts

   • Email on the user list

Intellectual Property Check

1. Your module must have a file presenting the providence review of the contents of your module including the copyright and licenses which apply to your module.

2. The file must be named and located as ‘REVIEW.md’

   The file should follow the standard layout of the file in the unsupported/example module.

3. This file describes any contents which do not follow the copyright and license of the project as a whole.

   • Deviations which require later fixes should have a link to a JIRA task explaining the issue and describing the plan to resolve the issue or remove the offending resource.

   • The goal here is to show that each and every file has been looked at, by hand, and any issues of copyright or licensing are known, and if possible addressed.

   • To make it easier to start you may wish to organise your review.apt file by package.

4. Fixing some of these issues in the past has required “stubbing” some of the jar dependencies with dummy code of the same signature from a third party JAR which we cannot distribute.

5. If your module includes code from third-party sources, include a NOTICE.txt file listing these sources and the associated licenses.

Follow the Developers Guide

The developers guide lists a number of coding conventions, we would like to ensure you line up with the following for a consistent project.

1. Coding Style: This is easy to check, load up the code formatting in eclipse and hit auto format.

2. Do not return null.

   A simple search for “return null” will often find a few things to think about.

3. Logging

   A few searches for “System.out.println” will often find content that needs to be logged.

4. Exception handling

   This one is harder to test, particularly with gobbling exceptions. Searching for “catch (Throwable” often leads to results.

5. Avoid Assumptions

6. Converting URLs to Files

7. Use of Assertions, IllegalArgumentException and NPE

8. Naming Conventions

   Running “FindBugs” will often catch inconsistent names.

9. Module Directory Structure

10. Testing

    Careful attention to use of “OnlineTest” for anything involving the internet. Running a build without your machine to the internet is an easy way to identify online tests.

    Maven indicates how long each test takes to run, use of “StressTest” can allow you to cut down on testing time as needed.

Test Coverage and Maven Profiles

The one most likely to cause grief is the JUnit testing requirement.

1. Please be aware that the tests may be performed by a build box such as hudson. Especially if they are on-line tests requiring the use of web services.

2. The test coverage expectation for the GeoTools library is 40%.

   • Coverage of 40% measured by a Jenkins control profile. You can supply a test fixture so the nightly builds can run against your database.

   • Plugins can extend provided “conformance test” if available to quickly reach 40%.

3. For help setting up your test fixture and maven profile for the nightly build box please contact the geotools-devel list.

How to measure test coverage:

1. Test coverage measured with cobertura or clover.

2. Run the following for your plugin:

   mvn clean cobertura:cobertura
   

3. The result is available for each module:

   target/site/cobertura/index.html

How to use a conformance test:

1. The author of an interface or abstract class may have provided a sample “conformance” test used to verify plug-in completeness and correctness.

2. For JDBC-NG datastore implementations

   • When implementing a new JDBC datastore please extend the provided abstract test class and customise it with your own test fixture.

   • For an example review the jdbc-hsql plugin

3. DataStore conformance in general can be based on MemoryDataStore example

   • Verify concurrency and event notification

   • Verify constant time performance of metadata queries

User Documentation

1. Currently have a very simple requirement for user documentation.

   • Please make something (anything!) available in GeoTools User Guide

2. It is recommended that you make a single example showing how to use your module or plugin (you can use a a code example if you must).

3. You may wish to refer to the writing guidelines for the user guide

   • Documentation

Ask to be included in the next release

1. Finally you can ask to be included in the next release.

   • Create a JIRA issue describing the new feature. This issue will be used in the pull request and release announcement.

   • Send an email to the list, indicating your module is ready and asking for review.

2. Chances are there will be questions and code review.

3. Create a pull-request moving your module from unsupported, and including it in the release:

   • Move your plugin from modules/unsupported to modules/plugin or modules/extension as appropriate.

   • Update release/pom.xml with a dependency on your module, taking care to keep the list of dependencies alphabetical so it is easier to maintain.

   • Update release/src/assembly/binaryDistDependencies.xml to include your module in the libs folder.

   • Move your module documentation to the appropriate location in the library documentation.

     A DataStore plugin for example is moved from unsupported/<module> to library/data/<module>.

   The jira issue for this pull request will be used in the release announcement.

4. Congratulations and welcome to GeoTools!