Skip to content

Latest commit

 

History

History
171 lines (121 loc) · 7.54 KB

CONTRIBUTING.md

File metadata and controls

171 lines (121 loc) · 7.54 KB
Raw

Contribution guide

Want to contribute? Great! We try to make it easy, and all contributions, even the smaller ones, are more than welcome. This includes bug reports, fixes, documentation, examples... But first, read this page.

Legal

All original contributions to jbanking are licensed under the ASL - Apache License, version 2.0 or later.

All contributions are subject to the Developer Certificate of Origin (DCO). The DCO text is also included verbatim in the dco.txt file in the root directory of the repository.

Code of conduct

In the interest of fostering an open and welcoming environment, jbanking team members and contributors are expected to follow our code of conduct.

Reporting an issue

This project uses GitHub issues to manage the issues. Open an issue directly in GitHub.

If you found a bug, please use the Bug report template and follow the indications.

Developer requirements

Before you start developing on jbanking you will need to :

  1. install Git,
  2. install a JDK 11+ (for instance Eclipse Temurin™),
  3. install Maven 3.8+.

It is recommended to install the JDK and Maven using tools like asdf or SDKMan!. Note that an asdf .tool-versions file that list the required JDK and Maven versions can be found in the root directory of the repository.

Also, make sure you have set up your Git authorship correctly:

git config --global user.name "Your Full Name"
git config --global user.email your.email@example.com

Code Style

jbanking has a strictly enforced code style. Code formatting is done by the formatter-maven-plugin. This maven plugin formats code using the Eclipse code formatter.

Code is automatically formatted each time you run mvn. You can also run it manually :

mvn formatter:validate # Validate code format
mvn formatter:format # Reformat code

If possible, you are encouraged to configure your IDE to format files with the project eclipse-formatter-config.xml.

Building and testing

Just execute the following commands:

git clone git@github.com:marcwrobel/jbanking.git
cd jbanking
mvn verify

Wait for a bit and you're done.

Benchmarking

In order to track the evolution of jbanking performances from version to version, some benchmarks are available here.

Releasing

In order to publish a release to Maven Central, you :

Then you can start the release process. First disable the main branch protection rules Require a pull request before merging and Require status checks to pass before merging.

Then execute the following commands:

cd jbanking
mvn release:prepare -Prelease
mvn release:perform -Prelease

If everything went fine, go to oss.sonatype.org and close/release the staging repository. Details are available on the OSSRH publish guide.

And finally:

  1. re-enable the disabled branch protection rules,
  2. declare the release on GitHub :
    1. copy the changelog content in the release notes,
    2. check Set as the latest release if appropriate,
    3. and check Create a discussion for this release to automatically create the release discussion),
  3. empty the changelog for the next release,
  4. update the Security Policy if necessary,
  5. update the current version in README.md,
  6. lock and unpin the discussion that relates to the previous version,
  7. pin the discussion that relates to the current version.
  8. close the milestone that was created for the released version.

Continuous Integration

Because we are all humans, and to ensure jbanking is stable for everyone, all changes must go through jbanking continuous integration. jbanking CI is based on GitHub Actions, which means that everyone has the ability to automatically execute CI in their forks as part of the process of making changes (except maybe the Sonarcloud and Sonatype lift analysis).

jbanking CI checks are:

  1. code is properly formatted,
  2. project builds,
  3. project test suite is passing,
  4. javadoc can be generated,
  5. SonarCloud analysis,
  6. GitHub CodeQL analysis,
  7. Sonatype lift analysis.

CI checks are automatically triggered on PR and on push on master or maintenance branches. All workflows are also automatically triggered weekly.

Note:

Contribution rules

To contribute, use a GitHub pull requests from your own fork. You can find more information on GitHub's documentation Contributing to projects.

Code reviews

All submissions need to be reviewed by at least one jbanking committer before being merged. GitHub Pull Request Review Process is followed for every pull request.

Coding Guidelines

  • Commits should be atomic and semantic. Please properly squash your pull requests before submitting them. Fixup commits can be used temporarily during the review process but things should be squashed at the end to have meaningful commits.
  • Git authorship (i.e. git user.name and user.email) must be properly set.
  • Tests and documentation are not optional. Don't forget to include tests in your pull requests. Also don't forget the documentation (reference documentation, javadoc...).
  • Make sure to launch the full test suite before creating your pull request.
  • @author tags are disallowed in the javadoc: they are hard to maintain, and we use the Git history to track authorship. GitHub also has this nice page with your contributions.
  • Do not add runtime dependencies to jbanking.

Security

jbanking does not have any runtime dependency. But it relies on some external libraries for testing purpose (such as guava, nv-i18n and OpenGamma Strata). In order to keep those libraries up-to-date we are using Dependabot.

jbanking is also following the OpenSSF Best Practices.