Liking cljdoc? Tell your friends :D

Maintainer Guide

Audience

You are a maintainer of this project.

Publishing a New Release

Is invoked from the command line via:

bb publish

The publish task locally validates:

  • local git

    • you are not on a fork

    • you are on the default 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

to run these validations without publishing, run bb pubcheck

Then also locally:

  1. bumps the version <release count> (our scheme is major.minor.<release count>)

    • Our version is stored in deps.edn under :aliases :neil :project :version

  2. applies version to:

    1. doc/01-user-guide.adoc

    2. CHANGELOG.adoc

  3. git commits: deps.edn doc/01-user-guide.adoc CHANGELOG.adoc

  4. git tags with release tag v<version>

  5. pushes commit

  6. pushes tag

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

  1. CI tests workflow is invoked

  2. a release jar is published to clojars

  3. a GitHub release is created

  4. cljdoc is informed of the new release

Relevant Sources

Scripts:

  1. bb.edn - tasks entry point

  2. script/publish.clj - client side work

  3. script/ci_publish.clj - ci side work

CI - We use GitHub Actions for this project

  1. .github/workflows/publish.yml

CI Config

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

Codecov.io token is configured as a CODECOV_TOKEN secret in this repo. Token was generated and populated by clj-commons GitHub org admins who have the privs to do such things. Hit them up in Clojurians Slack #clj-commons channel if you should ever need their help.

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. Annoying, but harmless.

❮Code of Conduct

Can you improve this documentation? These fine people already did:
lread & Lee ReadEdit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

Keyboard shortcutsReport a problemcljdoc on GitHub
× close