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 <https://github.com/pop-team/pop-java> and is open to merge requests for new developments.

Coding conventions

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

  • Indent with a hard-tab \t, ASCII 0x09
  • 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 CHANGELOG.md 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 CHANGELOG.md under the so-called UNRELEASED section.

  2. Update version

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

    Note

    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
    

    Note

    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
    

    Note

    • 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 gradle.properties file (generally stored in ~/.gradle/) like this:

      signing.keyId=YourKeyId
      signing.password=YourPublicKeyPassword
      signing.secretKeyRingFile=PathToYourKeyRingFile
      
      ossrhUsername=your-jira-id
      ossrhPassword=your-jira-password
      
    • The signing data must be generated, e.g. with GnuPG.

    • 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
    

    Note