= Developer Guide
:toclevels: 5
:toc:

== 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 https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[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:

[source,shell]
----
bb tasks
----

Optionally:

[source,shell]
----
$ 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):
[source,shell]
----
$ bb test
----

To only run a single suite:
[source,shell]
----
$ bb test --suite :unit
----

You can also include Cognitect test runner options:

[source,shell]
----
$ bb test --suite :unit --var cemerick.pomegranate.aether-test/live-resolution
----

...and/or Clojure version:

[source,shell]
----
$ 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!

[source,shell]
----
$ 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, you can for example:

[source,shell]
----
$ 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.

=== Outdated Deps
You can check for outdated dependencies via:

[source,shell]
----
$ 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
