Skip to main content

Contributing to sttp-oauth2

This is an early stage project. The codebase is prone to change. All suggestions are welcome, please create an issue describing your problem before contributing.

Please make sure to format the code with scalafmt using .scalafmt.conf from the repository root.

Working with documentation#

The documentation is built using mdoc combined with docusaurus v2.

To build the documentation make sure you have installed Node.js and Yarn according to docusaurus requirements.

Working on documentation locally using live reload#

For live reload you'd preferably need two console windows open. In both you should navigate to your repository root, then:

In the first terminal, launch sbt shell and run docs/mdoc --watch.

In the second one run:

cd ./website
npx docusaurus start

If it's your first time, remember to run npm install in the ./website directory

Documentation build workflow#

The raw documentation goes through a few steps process before the final website is created.

  • Raw data resides in ./docs directory, it follows regular docusaurus rules regarding creating documentation
  • The first step when building the documentation is to run docs/mdoc/. This step compiles the code examples, verifying if everything makes sense and is up to date.
  • When the build finishes, the compiled documentation ends up in ./mdoc/target/mdoc/
  • The last step is to build docusaurus. Docusaurus is configured to read files from ./mdoc/target/mdoc/ and generate the website using regular docusaurus rules.

Adding JSON implementations#

When adding a JSON implementation please follow the subsequent guidelines:

  1. Each JSON implementation should exist in a separate module, not to introduce unwanted dependencies.
  2. It should expose all necessary JsonDecoders via a single import following the import org.polyvariant.sttp.oauth2.json.<insert-json-library-name-here>.instances._ convention.
  3. It should make use of org.polyvariant.sttp.oauth2.json.JsonSpec test suite to ensure correctness.
  4. It should be included in the documentation (JSON Deserialisation).