02-developer-guide.adoc

Developer Guide

Table of Contents

• Audience
• Contributing
  • Issue First Please
  • Submitting a Pull Request
• Environmental Overview
  • Developer Prerequisites
  • Foundational Library
• Docs
• The Public API
• Babashka Tasks
  • Testing
  • Linting
  • Vulnerability scanning
  • Outdated Deps

Audience

You want contribute to, or learn about, the development of the Pomegranate library.

Contributing

We very much appreciate contributions from the community.

Issue First Please

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+

Foundational Library

Leiningen and other tools rely on Pomegranate behaving the way it does. We must be very careful when making changes.

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

When making changes to Pomegranate, understand that currently any public method is considered part of the public API.

We must be 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

Testing

Run Clojure tests. We have 2 suites:

• :unit - general unit tests

• :isolated - tests that pollute classloaders and classpath, and are therefore run separately

To run all test suites under Clojure 1.4 (our minimum supported version):

$ bb test

To only run a single suite:

$ bb test --suite :unit

You can also include Cognitect test runner options:

$ bb test --suite :unit --var cemerick.pomegranate.aether-test/live-resolution

…​and/or Clojure version:

$ bb test --clj-version 1.9

(specify :all to test against all supported Clojure versions)

Linting

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

$ bb lint-kondo
$ bb lint-eastwood

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:

$ bb nvd-scan

Outdated Deps

You can check for outdated dependencies via:

$ bb outdated

Before upgrading org.apache.maven.* deps, make sure there is a good reason to do so. Otherwise, don’t bother bumping these deps. Good reasons to bump org.apache.maven.* deps might be:

• to overcome a security vulnerability

• there is some necessary new/corrected behaviour