Skip to content

Latest commit

 

History

History
66 lines (45 loc) · 2.13 KB

CONTRIBUTING.md

File metadata and controls

66 lines (45 loc) · 2.13 KB

Contributing to JJWT

Thanks for your interest in improving JJWT! This guide covers building the project from source and running its test suite. For usage documentation, see the README.

Reporting issues

  • Security vulnerabilities: please follow SECURITY.md — do not open a public issue.
  • Bugs and feature requests: open a GitHub issue using the provided templates.

Building and installing from source

JJWT builds with JDK 17+ (the compiled bytecode targets Java 8). Use the included Maven wrapper:

./mvnw install

The build is a multi-module Maven reactor (api, impl, extensions, tdjar, bom).

To run the full verification build (the same goal CI runs):

./mvnw verify

By default the tests run on a single JVM (your build JDK), which is all you need for most changes. CI also runs them against a matrix of JDK vendors and versions. Testing locally against multiple JDK versions is optional, but if you want to, install them and generate the Maven toolchains configuration with the script in the repo:

./install-test-jdks.sh

New source files must carry the Apache 2.0 license header. Verify with ./mvnw license:check (use ./mvnw license:format to add missing headers).

SoftHSM and the PKCS11 tests

Pkcs11Test exercises JJWT against a real PKCS#11 token using SoftHSM. Install SoftHSM and OpenSC:

# macOS
brew install softhsm opensc

# Debian/Ubuntu
sudo apt-get install -y softhsm2 opensc

Then configure SoftHSM using the helper script:

impl/src/test/scripts/softhsm configure   # creates the SoftHSM user config if needed
impl/src/test/scripts/softhsm import      # (re)creates the 'jjwt' token and imports test keys

After that, ./mvnw clean verify will run the PKCS11 tests against the local token.

Submitting changes

  1. Fork the repository and create a branch off main.
  2. Make your change, including tests, and ensure ./mvnw clean verify passes.
  3. Open a pull request against main describing the change and the motivation.