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 4 spaces
- Always surround blocks with
{ }
- …
- …
Creation of a new release¶
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.
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.
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
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.
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.
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.
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.
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
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.
Update release details on GitHub
Please follow these steps:
- Go to the GitHub release page;
- Click on the new release link;
- Click on the
Edit tag
button (on the top right of the page); - Fill in the related fields;
- Click on the
Publish release
button.
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
- 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