= Maintainer Guide
:toclevels: 5
:toc:

== Audience
You are a maintainer of this project.

== Publishing a New Release
Is invoked from the command line via:

[source,shell]
----
bb publish
----

The publish task locally validates:

* local git
** you are not on a fork
** you are on master branch
** do not have any uncommitted code
** do not have any unpushed commits
** local head sha matches matches remote head sha
* changelog
** Has an "Unreleased" section with content

TIP: to run these validations without publishing, run `bb pubcheck`

Then also locally:

. bumps the version `<release count>` (our scheme is `major.minor.<release count>`)
** Our version is stored in `deps.edn` under `:aliases` `:neil` `:project` `:version`
. applies version to:
.. `doc/01-user-guide.adoc`
.. `CHANGELOG.adoc`
. git commits: `deps.edn` `doc/01-user-guide.adoc` `CHANGELOG.adoc`
. git tags with release tag `v<version>`
. pushes commit
. pushes tag

Then up on CI, the CI publish workflow is only triggered when it sees a release tag:

. CI tests workflow is invoked
. a release jar is published to clojars
. a GitHub release is created
. cljdoc is informed of the new release

== Relevant Sources

Scripts:

. `bb.edn` - tasks entry point
. `script/publish.clj` - client side work
. `script/ci_publish.clj` - ci side work

CI - We use GitHub Actions for this project

. `.github/workflows/tests.yml`
. `.github/workflows/publish.yml`

== CI Config

Clojars secrets are protected under the `publish` environment which is only referenced by `publish.yml`.

The nvd api token is stored under the `nvd` environment and refernced by `nvd_scanner.yml`.
Should you need to update the token, you can request one here: https://nvd.nist.gov/developers/request-an-api-key.
If you are using gmail, you can request a unique token for pomegranate CI by including `+pomegranate` in your email address, ex. `bob@gmail.com` becomes `bob+pomegranate@gmail.com`.

== Expected Oddities

When publishing, you will see both the `tests` workflow triggered and the `publish` workflow triggered (which also invokes the `tests` workflow).

This extra running of the `tests` workflow is GitHub Actions responding to changes committed as part of the publishing work.
A bit annoying, but harmless.
