Community Modules

This document describes the GeoServer community module process. It is a guide that describes how the GeoServer project takes in contributions from the community.

In GeoServer a module can fall into one of three classes:

  • core, those modules which GeoServer requires to function and are distributed with the main GeoServer distribution

  • extension, plug-ins available as separate artifacts from the main distribution

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

Creating a community module

Requirements

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

Process

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 to the rest of the GeoServer community the purpose and function of the extension to be added. The two best ways to do this are:

    1. send an email to the developers forum, or

    2. participate in a bi-weekly GeoServer meeting

    After explaining the intention, the approval of at least one Project Steering Committee member is needed before proceeding. Getting approval is easy as long as it is explained 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 git repository. To do this it is necessary to be granted commit status. The process for signing up for version control access is defined in the Committing section.

  3. Add a new module

    Once commit access is obtained the module can be added. 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.

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

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

  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>2.8-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 -->

    <!-- Spring Framework dependencies - DO NOT specify version (managed by BOM) -->
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-context</artifactId>
    </dependency>
    <!-- Spring Security dependencies - DO NOT specify version (managed by BOM) -->
    <dependency>
      <groupId>org.springframework.security</groupId>
      <artifactId>spring-security-core</artifactId>
    </dependency>
  </dependencies>
</project>

    Add the file to the root of the new community module, myCommunityModule/pom.xml

    Note

    When adding Spring Framework or Spring Security dependencies, never specify the version. GeoServer uses Bill of Materials (BOM) to manage these versions centrally. See the Maven Guide for more details on dependency management.

  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:

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

      <profiles>
  ...
  <profile>
    <id>myCommunityModule</id>
    <modules>
      <module>myCommunityModule</module>
    </modules>
  </profile>
</profiles>

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

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

    Warning

    If the community module depends on any other community modules, they too should be included in the profile definition.

    Warning

    Ensure that the name of the profile matches the name of the community module

Pending Release Profile

When a community module is maturing, but not yet ready for promotion to core or extension status, it may be assigned to the “pending release” profile. Modules in this profile are included in the standard release process. Their documentation should clearly describe the remaining work required for promotion, typically in terms of funding, real-world testing, or developer time.

Requirements

  1. The module is not site-specific and can be configured for use by the general GeoServer community.

    A community module of interest to multiple users would meet this goal; while a community module that has hard-coded a domain name would not.

  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 will be removed from the pending profile.

  3. The module passes all tests and QA checks

    The module must pass all tests and QA checks in order to be included in the release process.

  4. The module maintains 30% test coverage

    A minimum of 30% test coverage must be maintained by the module in order to be included in the pending profile.

  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 in the user manual

    Each module needs a page in the user manual documenting its function and usage. Tutorials and walk-throughs are encouraged. The documentation should clearly describe the remaining work required for promotion, to encourage users, developers and funders to help complete the module.

  7. The maintainer has signed the GeoServer Contributor Agreement

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

Process

  1. Get approval

    The first step is to get approval to move the module to pending status. This involves clarifying to the rest of the GeoServer community that the requirements are all met, as well as explaining what work is still needed to promote the module to extension status. The two best ways to do this are:

    1. send an email to the developers forum, or

    2. participate in a bi-weekly GeoServer meeting

    The approval of at least one Project Steering Committee member is needed before proceeding.

  2. Make sure the module has a ModuleStatus Spring bean declared, and set its status to PENDING, provide contact information and a description of what is needed to promote the module to extension status.

  3. Include the module in the pending profile of the community/pom.xml file.

  4. Update the website layout to list module for download:

    • _layouts/nightly_30.html

    • _layouts/nightly_main.html

    • _layouts/nightly_228.html

    • _layouts/release_228.html

Removing a module from the Pending Release Profile

A module in the pending release profile can be removed from it for one of two reasons:

  • The module maintainer is no longer active.

  • The module is breaking the build as a result of a core change, and the developer performing the change cannot wait for the module maintainer to fix it. When the build in the module is fixed, it can be re-added to the pending profile.

Promoting a community module to extension

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 (i.e. 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.

Requirements

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

  1. The module is not site-specific and can be configured for use by the general GeoServer community.

    A community module of interest to multiple users would meet this goal; while a community module that has hard-coded a domain name would not.

  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.

  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 passes all tests and QA checks

    The module must pass all tests and QA checks in order to be included in the release process.

  5. The module maintains 60% test coverage

    A minimum of 60% 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 has, the more credibility it gets.

  6. The module has no IP violations

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

  7. The module has a page in the user manual

    Each module needs a page in the user manual documenting its function and usage. Tutorials and walk-throughs are encouraged.

  8. The maintainer has signed the GeoServer Contributor Agreement

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

Process

  1. Submit a GeoServer Improvement Proposal

    To promote a community module the contributor must create a GeoServer Improvement Proposals (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 whether it is being promoted to a core module, or an extension.

    Core modules

    Core modules live under the root of the source tree:

    [geoserver]% mv src/community/myCommunityModule src/
[geoserver]% git add src/myCommunityModule
[geoserver]% git add --all src/community/myCommunityModule
[geoserver]% git commit -m "promoting my community module to a core module"

    Extensions

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

    [geoserver]% mv src/community/myCommunityModule src/extension
[geoserver]% git add src/extension/myCommunityModule
[geoserver]% git add --all src/community/myCommunityModule
[geoserver]% git commit -m "promoting my community module to an extension"

  3. Update the build

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

    Core modules

    1. Edit community/pom.xml and remove the profile for the community module

    2. Edit pom.xml under the root of the source tree and add a module entry:

      <modules>
  ...
  <module>myCommunityModule</module>
</modules>
    3. Edit web/app/pom.xml and move the dependency on the community module

      into the main dependencies section of the pom. Then remove the profile

    Extensions

    1. Copy the profile for the community module from community/pom.xml to extension/pom.xml

    2. Remove the profile from community/pom.xml

    3. Remove the release descriptor from community/pom.xml contained in the maven-assembly-plugin configuration section

    4. Remove the dependency from community/release/pom.xml

  4. Update the release process

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

    Extensions

    1. Create a new directory under release/src/extensions which matches the name of the extension

    2. Add the following to the new directory:

      1. A license called <module>-LICENSE.md which contains the license notice for the extension (linking to full licenses/ documents included below).

        Follow the dxf-LICENSE.md example:

        Extension License Notice
========================

DXFOutputFormat WFS Output and WPS PPIO for GeoServer
Mauro Bartolomeoli, GeoSolutions Sas

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

This GeoServer plugin is licensed under the GNU General Public License (GPL). For more information see license [notice](licenses/NOTICE.md) and the full [GPL](licenses/GPL.html).

This software is an extension for GeoServer. You can find full information
on it at https://www.geoserver.org

      2. A readme called <module>-README.md which contains instructions on how to install the extension.

        Follow the dxf-README.md example:

        DXFOutputFormat WFS Output and WPS PPIO for GeoServer
=====================================================

For more information http://docs.geoserver.org/latest/en/user/extensions/dxf/index.html

INSTALLATION
---------------------------
If you only need the WFS Output, copy `gs-dxf-core-*.jar` to `geoserver WEB-INF/lib`.
If you need both the WFS Output and the WPS PPIO, copy `gs-dxf-*.jar` to `geoserver WEB-INF/lib`.

Please note that the WPS PPIO needs the WPS extension to be installed, so please first download 
and install that.

USAGE
---------------------------

The DXFOutputFormat WFS Output adds support for two additional output formats for 
WFS GetFeature requests. The new formats, DXF and DXF-ZIP are associated to the 
"application/dxf" and "application/zip" mime type, respectively.
They produce a standard DXF file or a DXF file compressed in zip format.

The WPS PPIO adds dxf as an on output format option for WPS processes.

DXF is a CAD interchange format, useful to import data in several CAD systems.
Being a textual format it can be easily compressed to a much smaller version, so
the need for a DXF-ZIP format, for low bandwidth usage.

There have been multiple revisions of the format, so we need to choose a "version"
of DXF to write. The extension implements version 14, but can be easily extended
(through SPI providers) to write other versions too.

Request Example.

```
http://localhost:8080/geoserver/wfs?request=GetFeature&typeName=Polygons&
outputFormat=dxf
 
Output Example (portion).
  0
SECTION
  2
HEADER
  9
$ACADVER
  1
AC1014
...
  0
ENDSEC
...
  0
SECTION
  2
TABLES
...  
  0
TABLE
  2
LAYER
...
  0
LAYER
  5
2E
330
2
100
AcDbSymbolTableRecord
100
AcDbLayerTableRecord
  2
POLYGONS
 70
     0
 62
     7
  6
CONTINUOUS
  0
ENDTAB
...
  0
ENDSEC
  0
SECTION
  2
BLOCKS
  ...
  0
ENDSEC
  0
SECTION
  2
ENTITIES
  0
LWPOLYLINE
  5
927C0
330
1F
100
AcDbEntity
  8
POLYGONS
100
AcDbPolyline
 90
     5
 70
     1
 43
0.0
 10
500225.0
 20
500025.0
 10
500225.0
 20
500075.0
 10
500275.0
 20
500050.0
 10
500275.0
 20
500025.0
 10
500225.0
 20
500025.0
  0
ENDSEC
  0
SECTION
  2
OBJECTS
...
  0
ENDSEC
  0
EOF
```


Each single query is rendered as a layer. Geometries are encoded as
entities (if simple enough to be expressed by a single DXF geometry
type) or blocks (if complex, such as polygons with holes or collections).

Some options are available to control the output generated. They are 
described in the following paragraphs.

GET requests format_options
===========================

The following format_options are supported:

1. version: (number) creates a DXF in the specified version format 

2. asblock: (true/false) if true, all geometries are written as blocks
   and then inserted as entities. If false, simple geometries are
   directly written as entities.

3. colors: (comma delimited list of numbers): colors to be used for the
   DXF layers, in sequence. If layers are more than the specified colors, they
   will be reused many times. A set of default colors is used if the option is 
   not used. Colors are AutoCad color numbers (7=white, etc.).
   
4. ltypes: (comma delimited list of line type descriptors): line types
   to be used for the DXF layers, in sequence. If layers are more than 
   the specified line types, they will be reused many times. If not specified,
   all layers will be given a solid, continuous line type. A descriptor
   has the following format: ``<name>!<repeatable pattern>[!<base length>]``,
   where `<name>` is the name assigned to the line type, `<base length>` (optional)
   is a real number that tells how long is each part of the line pattern
   (defaults to 0.125), and `<repeatable pattern>` is a visual description
   of the repeatable part of the line pattern, as a sequence of - (solid line),
   `*` (dot) and `_ `(empty space). For example a dash-dot pattern would be expressed
   as `--_*_`.

5. layers: (comma delimited list of strings) names to be assigned to
   the DXF layers. If specified, must contain a name for each requested
   query. By default a standard name will be assigned to layers.

POST options
===========================

Unfortunately, it's not currently possibile to use format_options in POST
requests. The only thing we chose to implement is the layers options, via
the handle attribute of Query attributes. So, if specified, the layer
of a Query will be named as its handle attribute.
The handle attribute of the GetFeature tag can also be used to override
the name of the file produced.

BUILD FROM SOURCE
---------------------------

1. Install JAVA SDK
   
   Download and install the Java SDK.

   Create an environment variable called JAVA_HOME and point it to your Java SDK 
   directory.
   Then modify the PATH variable and add: ;%JAVA_HOME%/bin
   Apply the changes.

2. Download and install Maven

   Windows: http://www.apache.org/dyn/closer.cgi/maven/binaries/maven-2.0.4.exe
   
   Linux: http://www.apache.org/dyn/closer.cgi/maven/binaries/maven-2.0.4.zip

   If you are using Linux, execute the following commands:
   export M2_HOME=/usr/java/maven-2.0.4
   export PATH=$PATH:$M2_HOME/bin

3. Build Source Code

   Go to the command line and navigate to the root of the source tree.
   Execute the command:
   
   mvn install

   If it fails, just try again. It trys to download jars and some might not be 
   available at that time. So just keep trying.

DEPLOY THE DXFOUTPUTFORMAT
---------------------------

1) copy `core/target/gs-dxf-core-*.jar` to geoserver `WEB-INF/lib`.

2) restart geoserver.

DEPLOY THE DXFWPSPPIO
---------------------------

1) copy `wps/target/gs-dxf-wps-*.jar` to geoserver `WEB-INF/lib`.

2) restart geoserver.

        Warning

        Don’t skip this step.

      3. Any “static” files that are required by the extension.

        An example would be data files or a proprietary driver not available for download via maven.

    3. Create a release assembly called ext-<module>.xml under the release src/assembly directory.

      Follow the example of ext-dxf-xml:

      <assembly>
  <id>dxf-plugin</id>
  <formats>
    <format>zip</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <fileSets>
    <fileSet>
      <directory>release/target/dependency</directory>
      <outputDirectory></outputDirectory>
      <includes>
        <include>gs-dxf*.jar</include>
      </includes>
    </fileSet>
    <fileSet>
      <directory>release/target/html/licenses</directory>
      <outputDirectory>licenses</outputDirectory>
      <includes>
         <include>GPL.html</include>
         <include>NOTICE.html</include>
      </includes>
    </fileSet>
  </fileSets>
  <files>
     <file>
       <source>release/extensions/dxf/dxf-README.md</source>
       <outputDirectory></outputDirectory>
       <destName>README.txt</destName>
     </file>
     <file>
       <source>release/target/html/extensions/dxf/dxf-LICENSE.html</source>
       <outputDirectory></outputDirectory>
       <destName>LICENSE.html</destName>
     </file>
     <file>
       <source>release/target/html/extensions/dxf/dxf-README.html</source>
       <outputDirectory></outputDirectory>
       <destName>README.html</destName>
     </file>
  </files>
</assembly>

      • Add additional include elements in the root folder (outputDirectory empty) for the jar dependencies of the module

      • Add additional include elements in the licenses folder (outputDirectory licenses) for licenses required

      • Add an additional fileSet if there are any static file dependencies of the module required by the module

      • Use file with destName for any individual files that require renaming

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

    5. Add an entry for the release descriptor to the root pom.xml of the source tree (i.e. one step up from the release directory):

      <!-- artifact assembly -->
<plugin>
  <artifactId>maven-assembly-plugin</artifactId>
  <version>2.1</version>
  <configuration>
    <descriptors>
     <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>

    1. Update the /doc/en/user/source/community documentation:

      • Add a section to the user manual for the new module:

        Create a folder:

        • community/%module%

        • community/%module%/files - example files

        • community/%module%/img - screen snaps

        • community/%module%/index.rst

        • community/%module%/installing.rst

        • community/%module%/usage.rst

      • Include module in community/index.rst toctree:

        .. toctree::
   :maxdepth: 1

   backuprestore/index
   cog/index
   ...
   %module%/index.rst

      • When writing installing.rst use the sphinx external link download_community to generate a download link for the current release.

        To install the JDBCConfig module:

#. Visit the :website:`website download <download>` page and download :download_community:`jdbcconfig`.

      For more information see documentation guide.

    2. Download and a contributor license agreement as pdf for txt file:

    3. Follow the instructions on the form to submit it.

Demoting a community module

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:

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

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

Requirements

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

  1. The module has 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.

Process

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. Both notify GeoServer Devel mailing list and GeoServer User forum that module is in danger of reverting to community status. Wait a few days to see if anyone steps up to take on maintainership or provide funding.

  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

Stepping down from module maintainership

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 - maybe someone who has contributed to the module before.

Previous: Review
Next: Service Providers