Developer Guide — clj-commons/clj-yaml 1.0.26

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

The current version of Babashka. The current version of Clojure. JDK8+ 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

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)

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

$ bb lint