Contribution guidelines

Contributing to POP-Java is very simple. All the code is hosted in a public git repository hosted on gitlab. It can be found at <> and is open to merge requests for new developments.

Coding conventions

When writing new code for POP-Java you should always:

  • Indent with 4 spaces
  • Always surround blocks with {  }

Creation of a new release

  1. Update changelog file

    All notable changes to the POP-Java project will be documented in the file as follows (source: SemVer). Given a version number MAJOR.MINOR.PATCH, increment the:

    • MAJOR version, when incompatible API changes are made;
    • MINOR version, when functionalities in a backwards-compatible manner are added;
    • PATCH version, when backwards-compatible bug fixes are made.

    Additional labels for pre-release (e.g. Beta, RC1) and build metadata may be added as extensions to the MAJOR.MINOR.PATCH format.

    For each new version released, the related section will list its novelties under the following potential sub-sections: Features, Bug Fixes and BREAKING CHANGES.

    New functionalities, which are not yet released, will be listed at the top of the under the so-called UNRELEASED section.

  2. Update version

    Increment the version number of POP-Java in the build.gradle file.


    This step is mandatory in order to publish a new Maven release.

  3. Update author file

    All current and/or previous authors (core committers) shall be listed in the AUTHORS file as follows:

    Current core committers:
    * Beat Wolf
    * Jonathan Stoppani
    * Christophe Gisler
    Previous core commiters:
    * Beat Wolf
    * Davide Mazzoleni
    * Valentin Clément
  4. Build Jar

    A fat Jar version of POP-Java must be built locally in order to run the tests by using the following command:

    $ ./gradlew fatJar


    Make sure you use Java JDK 8 (not 9) in order to build POP-Java. Otherwise it will not run under Java 8.

  5. Run tests locally

    POP-Java must be tested locally by using the following command:

    $ ./gradlew test

    All tests must pass before going to the next step.

  6. Build and upload Maven package to OSSRH

    Build the POP-Java Jar files and signing files required for the Maven package, and upload (deploy) them to the OSSRH repository by using the following commands:

    $ ./gradlew clean
    $ ./gradlew uploadArchives


    • We first clean the build directory to get rid of the fat Jar bundle, which must not be deployed to the OSSRH repository.

    • To perform this step, one must have a Sonatype JIRA login and credentials in his file (generally stored in ~/.gradle/) like this:

    • The signing data must be generated, e.g. with GnuPG.

    • Newer (2.1+) GPG versions use a new keyring file format (.kbx). You need to convert/export your key to the old format.

      gpg --export-secret-keys -o secring.gpg

    • With the 2.1+ GPG version you also need to use a special command to list the available keys to get the correct id.

      gpg --list-keys --keyid-format short

    • More information about the Maven packaging process is given on the OSSRH Guide.

  7. Commit, tag and push

    Commit your changes to the project, tag your version and push them:

    $ git commit -m "My commit message"
    $ git tag -a v2.1.0 -m "my version 2.1.0"
    $ git push origin master
    $ git push --tags
  8. Wait for tests to pass and documentation to build

    Here nothing to do but wait. While one or more tests fail, please fix the related bugs and go back to previous step.

  9. Update release details on GitHub

    Please follow these steps:

    1. Go to the GitHub release page;
    2. Click on the new release link;
    3. Click on the Edit tag button (on the top right of the page);
    4. Fill in the related fields;
    5. Click on the Publish release button.
  10. Release deployed Maven package from OSSRH to the Central Repository

    Automatically close and release the staging version from OSSRH to the Central Repository by using the following command:

    ./gradlew closeAndReleaseRepository


    • To pass this step, the deployed files are verified and thus must fulfil some requirements.
    • This step was fully automatized thanks to the Gradle Nexus Staging Plugin. However, it can manually be done on the OSSRH website as described here.
    • It takes about 2 hours to synchronize between OSSRH and the Central Repository