Developer Guide — clj-commons/clj-yaml 1.0.28

Developer Guide

Audience

You want contribute to, or learn about, the development of the clj-yaml library.

Contributing

We very much appreciate contributions from the community.

If you have an idea or a fix, please do raise a GitHub issue before investing in any coding effort. That way we can discuss first. Writing code is the easy part, maintaining it forever is the hard part.

That said, if you notice a simple typo, a PR without an issue is fine.

Submitting a Pull Request

Please never force push on your PR, as this makes reviewing incremental changes impossible for us. When we merge your PR, we’ll usually squash it, so that will clean up any rambling work in progress.

Environmental Overview

Developer Prerequisites

Java Development Kit, minimum version 8 (we currently validate against versions 8, 11, 17 and 21)
The current version of Clojure (if you are on Windows we recommend installing via clj-msi).
The current version of Babashka.
The current version of GraalVM (if you want to run native image tests)
Some knowledge of Java if you are going to add/modify Java code (there’s not much!).

Babashka Built-in

Clj-yaml is built into babashka.

Any changes we make to clj-yaml will take this fact into consideration.

Docs

All documentation is written in AsciiDoc. @lread likes to follow AsciiDoc best practice of one sentence per line but won’t be entirely pedantic about that.

We host our docs on cljdoc.

The Public API

Like many other libraries, clj-yaml did not clearly distinguish its public API from its implementation details.

A library with an explicitly defined public API reduces the surface area of what we need to be careful not to break and gives us the freedom to change what is clearly internal.

Because users of clj-yaml have made full use of the clj-yaml.core namespace, we continue to support it.

But moving forward, we will be very careful not to expose what we feel are implementation details.

Babashka Tasks

We use Babashka tasks, to see all available tasks run:

bb tasks

Optionally:

$ bb clean
$ bb download-deps
$ bb compile-java

Testing

Run all Clojure tests

$ bb test

You can also include cognitect test runner options:

$ bb test --var 'clj-yaml.core-test/emoji-can-be-parsed'

…and/or Clojure version:

$ bb test --clj-version 1.9

(defaults to 1.8, specify :all to test against all supported Clojure versions)

GraalVM testing

With your dev environment configured to a current version of GraalVM run:

$ bb test-native

There is currently no facility to run a subest of tests.

We include a native-image config in our jar file for GraalVM to pick up. To ensure that this works, we natively compile our test sources against a locally built clj-yaml jar.

Our clj-yaml.native-test-runner is currently hand-coded, if you add any test namespaces you’ll need to adjust it.

Linting

Our CI workflow lints sources with clj-kondo, and eastwood - and you can too!

$ bb lint-kondo
$ bb lint-eastwood

Or to run both: bb lint

Vulnerability scanning

We automatically scan for vulnerabilities in our dependencies on CI. If you want to run this work locally, you can for example:

NVD_API_TOKEN=your-token-here bb nvd-scan

Replace your-token-here with your personal nvd api token which you can easily request from https://nvd.nist.gov/developers/request-an-api-key.