Havoc -- create a release suited for publishing to Github

Cry 'Havoc,' and let slip the dogs of war
— Mark Antony in Act 3, Scene 1 of Shakespeare's Julius Caesar

Check out Havoc's Releases page (also on right sidebar) for examples of what it does!

Synopsis

% HAVOC_OPT=... havoc
Creating artifacts ...

Read The Havoc Commit Spec for details on making standard commits that will show up beautifully in a "Release Doc".

This is a simple couple of scripts that interactively create a documented "Release" suited for publishing; eg, to Github. Any executable script(s)/binarie(s) can become something that is a "releasable package" with realease documentation and a predictable set of artifacts. Then your users can quickly discover, download, understand, and run your work with minimal effort.

One of Havoc's goals is to make releases consistent. If you browse across various projects' Release pages, you won't see two that are alike!

Havoc's wardoc (invoked implicitly) discovers commits since your last release and categorizes and auto-documents them into Markdown that's suitable as a pretty release page (that passes markdownlint if you care).

Havoc's eponymous main script (which is all you need to invoke) creates a release that is uploaded to Github release pages (and others maybe someday). The release consists of:

• a "release doc" capturing all changes since prior release (or inception); this becomes your release page and is published on github as such
• a tarball (myproj.tgz) containing your binaries from your bin/
• a matching checksum (myproj.tgz.sha256)
• a generated man page (myproj.1r.gz), if manget is installed

Tools like eget can leverage all of those to give your users a trivial install experience.

Installation

If you use eget (highly recommended!), simply run: eget micahelliott/havoc. Otherwise, you can download havoc and wardoc from bin/ to somewhere on your $PATH.

Dependencies

Havoc should run fine on any Linux or Mac or WSL.

• Uploading presently relies on having gh (the Github CLI) installed.

• [OPTIONAL] Generating a summary relies on llm cli.

• [OPTIONAL] If you have manget installed, you can generate and publish a man page (automatically generated from README) as another convenient artifact.

• [OPTIONAL] If you have bat installed, you will see a nicer local display of the generated doc.

Usage

Havoc wants a little structure: releasable scripts and binaries in bin/, and a directory releases/ for it to create releases and docs. So if you haven't already:

mkdir bin releases; mv MYRUNNABLES bin

You may want to add releases/ to .gitignore since it will end up with a bunch of tarballs. Which is kinda the point of having a separate dir for this. Or something like git-lfs could be used.

![NOTE] Don't create/push "git tags" yourself -- havoc manages tags for you!

Generate a "git release doc/tag" file, releases/v2025.02.02.md, and release tarball:

% havoc
Creating artifact of runnable tools in bin dir: releases/havoc-v2025.02.06.tgz
./
./havoc
./wardoc

Will create and push git tag: v2025.02.06
Proceed? [y/n] y
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
To github.com:MicahElliott/havoc.git
 * [new tag]         v2025.02.06 -> v2025.02.06
Created release doc ‘releases/v2025.02.06.md’
Edit? [y/n] n
Creating a new release on github
https://github.com/MicahElliott/havoc/releases/tag/v2025.02.06

The (editable) Markdown file looks something like this:

**[Full Changelog](https://github.com/MicahElliott/captain/compare/v2025.01.09...v2025.02.02)**

## Fixes

- :bug: Be smarter when invoked in non-git dir (894434f)

## Features

- :sparkles: On failures print more helpful info (e729228)
- :sparkles: Timeout long commands, default 10s (ba03f64)

## Configuration

- :wrench: Improve install docs (ecbb3a6)

---
_This release was created with [havoc](https://github.com/MicahElliott/havoc)._

Advanced usage (optional)

Frequent releases

If you need to release multiple times on a given day, you can pass an arg to Havoc indicating an additional suffix. This is also useful for creating a -alpha or -beta or some such label.

LLM summaries

LLMs are well suited to the task of summarizing commits. Havoc supports such automatic generation. It uses llm, so you have to configure it if you want to use this feature. With this option, a "Summary" is added to the top of the categorized commit listing. It is based on full commit bodies, not just subject line.

Generated SHA for verification

Along with the release archive tarball, a similarly named file with a .sha256 suffix is generated. This can be inspected manually, or can be used automatically by eget (see below).

Configuration

You can change the format of each commit that is shown in the bulleted lists in the release doc. Eg, if you wanted to also see dates (%aI) and author names (%an) use the env var:

% HAVOC_COMMIT_FORMAT='%aI %s (%h) <%an>' havoc

There is a "tabular" option (HAVOC_TABULAR=1) that can print a table instead of a bulletted list of commits. It will use Message, Author, Date fields (and header). This is a nice way to go especially if you install Github Sort Content in your browser, for sorting any table.

Team Mode

If you're in an org with multiple teams, you may want to organize commits/reporting accordingly. You can run in team mode with:

% HAVOC_TEAMWISE=1 havoc

The team file should be named devteams.tsv and live in the directory you're running havoc from. The TSV format is like:

Larry David	Writers
Billy Crystal	Writers
Martin Short	Writers
Chris Farley	Cast
Bill Murray	Cast
Tina Fey	Cast
Lorne Michaels	Producers
Dick Ebersol	Producers

That will print an additional summary for each team and create sections for each. The LLM prompt for teams is focused more on categorizing into noteworthy projects.

Anti-features

Havoc doesn't try to do anything smart with auto-creating versions according to SemVer. It presently is only CalVer oriented for its simplicity.

It also does not deploy a release for you. It's up to you to get binaries onto machines, run migrations, etc.

Background

I like the idea of gitmoji but find its CLI to be overkill (huge, slow, clunky, and too many categories). So Havoc supports pretty close to a subset, which comprise my opinionated choosing. See those supported emojis in the source (not worth re-documenting here).

I realize that gh is able to do a lot of what Havoc does. But Havoc supports a more flexible workflow, not requiring PRs for everything, and not requiring SemVer.

Havoc also supports your standard categories from Conventional Commits, and from Gommit. IOW, if you're using any semi-standard prefixed commit convention, Havoc aims to work for you (or should soon enough).

Other related/helpful tools

Now that you have an officially released project (YAY!), you want people to easily install (and update!) it. These minimal tools play nice with Havoc and make that process very simple:

• Pacrat — A minimal yet flexible package manager for a variety of package types and OSs, geared toward installing CLI tools
• Eget — Easily install prebuilt binaries from GitHub

Fancy alternatives

I considered using git-cliff but ...