A process for managing GeoServer extensions.

Motivation Proposal Feedback Voting Links

Justin Deoliveira

1.7.0

Accepted

As more community modules mature to the point of being considered a stable, a formal process is needed to define exactly what the process is for adding a community module, and what is required in order to promote a community module to a core module, or to an extension.

This document defines three types of modules:

1. core, those modules which GeoServer requires to function and are distributed with the main GeoServer distribution.
2. extension, plug-ins available as separate artifacts from the main distribution.
3. community, experimental or unstable modules which are not part of the release process

Every module added to GeoServer has its origin as a community module. If the module becomes stable enough it will eventually become part of the main GeoServer distribution either as a core module, or as an extension.

This proposal outlines the process of adding a community module, and defines the requirements for promoting a community module to a core or extension module.

Creating a Community Module Promoting a Community Module Demoting a Community Module Stepping Down from Maintainership

The single requirement for adding a community module is the approval of one Project Steering Committee member.

The following outlines the steps to be taken in order to add a new community module.

1. Get Approval

The first step is to get approval to add the community module. This involves first explaining the purpose and function of the extension you wish to add to the GeoServer community. The two best ways to do this are:

1. Send an email to the developers list, or
2. Participate in a weekly IRC meeting

After explaining your intentions, you need the approval of at least one Project Steering Committee member before proceeding. Getting approval is easy as long as you can show that the extension will be useful to other users or developers.

2. Get Version Control Access

The next step is to create the community module in the subversion repository. To do this you need to be granted commit status.

( It is important to note that once you are granted commit status it is limited to the community module only.

3. Add a New Module

Once you have commit access you can add the new module. All community modules live under the directory community, directly under the root of the source tree. The community modules on trunk can be found "here":http://svn.codehaus.org/geoserver/trunk/src/community .

For example, from the root of the GeoServer source tree:

[geoserver]% cd community
[geoserver/community]% svn mkdir myCommunityModule
[geoserver/community]% svn commit -m "adding my community module" myCommunityModule

4. Add a Maven POM

Every module in the build requires a maven pom file, pom.xml. Use the following as a template:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.geoserver</groupId>
    <artifactId>geoserver</artifactId>
    <version>1.7.0-SNAPSHOT</version> <)~~- change this to the proper
GeoServer version~~-\>
 </parent>

<groupId>org.geoserver</groupId>
 <artifactId>myCommunityModule</artifactId>
 <version>1.0-SNAPSHOT</version>
 <packaging>jar</packaging>
 <name>My Community Module</name>

<dependencies>

<!-- add any dependencies your module has here -->
</dependencies>
</project>

Add the file to the root of your new module. IE myCommunityModule/pom.xml.

5. Add a Build Profile

The final step involves adding the new module to the maven build, and in particular adding a build profile for it. To do this:

• Edit community/pom.xml and add the following inside of the <profiles> element:

<profiles>
 …
 <profile>
 <id>myComunityModule</id>
 <modules>
 <module>myCommunityModule</module>
 </modules>
 </profile>
 </profiles>

• Edit web/pom.xml and add the following inside of the <profiles> element:

<profiles>
 …
 <profile>
 <id>myCommunityModule</id>
 <dependencies>
 <dependency>
 <groupId>org.geoserver</groupId>
 <artifactId>myCommuityModule</artifactId>
 <version>1.0-SNAPSHOT</version>
 </dependency>
 </dependencies>
 </profile>
 </profiles>

(!) If your community module depends on any other community modules, they too should be included in the profile definition (!) Ensure that the name of the profile matches the name of the community module

h3. Promoting a Community Module

Once a community modules becomes "stable", it may be promoted to a core or extension module. Which depends on the nature of the community module. If the module is plug-in based (ie. it provides functionality that some users may want, but others may not) then it should become an extension. Otherwise it should become a core module.

h4. Requirements

The following properties must hold true in order to promote a community module:

1. The module has at least a "handful" of users.

In order to avoid cluttering the main code base, only those community modules which are of interest to at least 3 users (this may include the maintainer) are promoted.

2. The module has a designated and active maintainer.

Every core and extension module requires a module maintainer. The job of the maintainer is to fix bugs and address issues which arise with the module. If a community module is promoted and the maintainer "drops off", the module is in danger of being demoted back to community status. See Demoting a Community Module for more details.

3. The module is considered "stable" by the majority of the PSC.

A module will only be promoted if it is deemed "stable" by the majority of the PSC. Those PSC members deeming it "unstable" must provide a reasonable justification for the assertion.

4. The module maintains 40% test coverage.

A minimum of 40% test coverage must be maintained by the module in order to be promoted. Of course higher coverage is encouraged. The more test coverage a community module the more credibility it gets.

5. The module has no IP violations.

The module must not contain any code with a license or copyright that violates the GPL.

6. The module has a page on the Wiki.

Each module needs a page on the wiki documenting its function and usage. Tutorials and walk-throughs are encouraged.

7. The maintainer has signed the GeoServer Contributor Agreement.

The Open Planning Project (TOPP) retains all copyright on code released as part of GeoServer. Since core and extension modules are released along with the rest of GeoServer, the maintainer of said modules must agree to assign copyright of code to TOPP.

h4. Process

1. Submit a GeoServer Improvement Proposal

To promote a community module the contributor must create a [GeoServer Improvement Proposal](GEOSDOC:2 GeoServer Improvement Proposal) (GSIP). The proposal must then go through the regular feedback and voting process.

2. Move the Module

Once the proposal is accepted, the next step is to move the module out of the community space. Where the module ends up depends on wether it is being promoted to a core module, or an extension.

Core Modules

Core modules live under the root of the source tree.

[geoserver]% svn move community/myCommunityModule .
[geoserver]% svn commit -m “promoting my community module to a core
module” myCommunityModule community/

Extensions

Extension modules live under the extension directory, under the root of the source tree.

[geoserver]% svn move community/myCommunityModule extension [geoserver]% svn commit -m “promoting my community module to an extension” extension community

3. Update the Build

Once the module has been moved, the maven build must be updated.

Core Modules

• Edit community/pom.xml and remove the profile for the community module
• Edit pom.xml under the root of the source tree and add a module entry

<modules>
 …
 <module>myCommunityModule</module>
 </modules>
```

* Edit `web/pom.xml` and move the dependency on the community module into the main dependencies section of the pom. Then remove the profile.

_Extensions_

* Copy the profile for the community module from `community/pom.xml` to `extension/pom.xml`
* Remove the profile from `community/pom.xml`

*4. Update the Release Process*

The next step is to include the new module in the release process.

_Core Modules_

* Edit `release/src.xml` and add an `<include>` for the module:

… … org.geoserver:myCommunityModule …

_Extensions_

* Create a new directory under `release/extensions` which matches the name of the extension
* Add the following to new the directory:
* A license called '<module>-LICENSE.txt' which contains the license for the extension
* **Don't skip this step!** A readme called '<module>-README.txt' which contains instructions on how to install the extension
* Any "static" files that are required by the extension (example would be a proprietary driver not available for download via maven)
* Create a release descriptor called 'ext-<module>.xml' under the `release` directory which follows the following structure (where "%module%" is the name of the module):

• Add additional include elements in the second fileSet for the jar dependencies of the module
• Add additional include elements in the third fileSet for the static file dependencies of the module
• Add a dependency from release/pom.xml to the extension module:

<dependencies>
 …

<dependency>
 <groupId>org.geoserver.extension</groupId>
 <artifactId>%module%</artifactId>
 <version>%version%</version>
 </dependency>
 …
 </dependencies>

    # Add an entry for the release descriptor to the root `pom.xml` of the source tree (ie. one step up from the `release` directory):

<!-- artifact assembly -->
<plugin>
 <artifactId>maven-assembly-plugin</artifactId>
 <version>2.1</version>
 <configuration>
 <descriptors>
 <descriptor>release/src.xml</descriptor>
 <descriptor>release/war.xml</descriptor>
 <descriptor>release/javadoc.xml</descriptor>
 <descriptor>release/bin.xml</descriptor>
 <descriptor>release/doc.xml</descriptor>
 …
 <descriptor>release/ext-%module%.xml</descriptor>
 </descriptors>
 </configuration>
 </plugin>

5. Update the Documentation

The final step in the process is to add the wiki page for the module to the Users Guide.

TODO: We have yet to figure out what the parent pages will be. Once the documentation revamp occurs update this section.

Core Modules

_Extensions

6. Download the Contributor Agreement

Download and fill out the GeoServer Contributor Agreement Form . To submit it follow the instructions on the form itself.

For one reason or another a module is neglected and becomes unmaintained. When this happens the GeoServer PSC essentially becomes the maintainer and may decide to do one of two things:

• Assume Maintainership In this case someone (may be more than one person) on the PSC agrees to take on maintainership duties responsibilities for the module, such as bug fixing.
• Demote the Module If no one steps up to maintain the module it may be demoted back to community status. If and when a module is demoted depends on the circumstances. If the module is relatively “quiet” in that it just works and not many bug reports arise from it, it may be left alone and not demoted.

The following properties must hold true in order to demote a module back to community status:

1. The module no designated maintainer

The module maintainer has stepped down or is unreachable and has not been active for a number of weeks.

2. The module is problematic

The module contains one or more issues with blocker status, or contains a “handful” of issues with high priority.

The following outlines the steps to demote a module to community status.

1. Call for a Maintainer

Before demoting the module first try to find a new maintainer for it. Send an email to both the developer and user list advertising the module is in danger of getting pushed back to community status. Wait a few days to see if anyone steps up to take on maintainership.

2. Move the Module and Update the Build

If no one steps up to take on the maintainer role, reverse the steps described here, taken to promote the module. In summary:

1. Move the module back to the community directory.
2. Disable any of the modules release artifacts
3. Move the profile for the module from extension/pom.xml to community/pom.xml in the case of an extension module
4. Move the dependency from web/pom.xml into a profile in the case of a core module.

Often a module maintainer does not have the time or resources to continue to maintain a contribution. This is understood and is a fact of life in the open-source software world. However, to relieve the burden on the project and PSC, the following steps taken by any maintainer stepping down are highly appreciated.

1. Give Notice

The more time you can give to the project in lieu of your departure the better. Send an email to the developers list as soon as you know you will be dropping off.

2. Find a New Maintainer

While often not possible, any attempt to find a new maintainer for the module is greatly appreciated.

Andrea Aime: +1 Alessio Fabiani: +1 Justin Deoliveira: +1 Jody Garnett: +1 Simone Giannecchini: +1 Rob Atkinson:

JIRA Task Email Discussion Wiki Page