Publishing Software

I have a few conventions I use for publishing most of my software. They're sort of rules, and I bend them sometimes, but the core of them is this —

1. Documentation always ships alongside code. If publishing to a forge, the documentation should be natively readable.
2. Applications should carry their own documentation. If I just have a copy of the binary, I should be able to figure out how it works purely by interrogating it. This can be self-explanatory, particularly in well-designed GUIs¹, but with command-line apps or certain kinds of application, this isn't so. Documentation must be available in an obvious way.
3. Version numbers should exist in as few places as possible, because even one number is easy to forget to change when publishing. I usually embed them as a VERSION string for programs or MAJOR, MINOR, PATCH constants for libraries, and let my build tooling parse those. See the Meander build.sh for an example of this.

For the second point, especially in command-line apps, I always program in every possible version of the help command, even if they don't fit the convention of the rest of the app. So I'll usually have help, usage, -h, --help, etc., all available to catch the request. As long as the user thinks to try one of them, they'll be able to learn everything else from the documentation they're now presented with.

Publication Checklist

Because I've been burned several times by accidentally forgetting to change a version number or pushing a release tag before I meant to or accidentally having mismatched versions of docs side-by-side — and no doubt, even with this checklist, will continue to make impatient human errors — I've tried to create a little system to follow to catch all of this before I ship things.

This seems a bit silly, but I miss one of these things almost every time I update something, and it drives me mad every time.

• Are all of the changes intended to be in a patch made? Has any part not been completed?
• e.g: Does the new feature have its command-line argument exposed properly?
• e.g: Does the new feature need a special usage text change or is this covered by documentation?
• Have the changes been documented everywhere and confirmed to match?
• Readmes
• help command docs
• Website(s)
• Publication pages (itch.io, Steam, etc.)
• Have you changed the version number internally and externally, everywhere it must be seen?²
• Has it been changed in the code?
• Has it been changed in the help docs if applicable?
• Has it been changed in the published documentation?
• Has it been changed on any websites that point to the latest version?
• Has it been it changed on Itch or Steam or its storefront?
• Are there any URLs that reference the version in documentation, especially for libraries?
• Are there any on external websites?
• Are there less obvious places, like the frontmatter of a docs file, or a redirect to the latest version?
• Have the changes been documented in a changelog file, if relevant?
• Have you made certain you've cleaned up? Are there any stray debug printfs, @nocheckin tags, or other ephemera that need dealing with?

If a release and/or changelog must be published, ensure the source of truth documentation has been distributed to all relevant endpoints:

• Publish any new or changed features down into the internal help docs.
• Copy the new documentation master into Obsidian under its version number for posterity and publication.
• Check any URLs and versions here that cross-populate and ensure it actually gets published in all relevant locations.

Once any part of the distribution ecosystem has been published:

• Have you published it on the forge as a release or just pushed it?
• Have you published it on its storefront as an update?
• Have you referenced it on social media, if relevant?
• Have you updated your or the project's website accordingly?

Release / Changelog Template

This is the template I use for most of my release notes and the changelog.md files in software projects. In changelogs, the heading becomes the version number and all heading levels get bumped up by one.

# Patch Release
# Minor Release
# Major Release

or in changelogs:

# v0.0.0

Patch Release
Minor Release
Major Release

Delete whichever heading is not relevant. Write any initial or introductory notes here. Thank contributors if necessary.

## Features

List new features as simple one-liners, or sub-bullets if necessary. Don't go on too long.

- x

## Bugs

Ditto for fixed bugs. Be descriptive only if specificity is needed.

- x
  
## Internal

Document any internal changes here that may be relevant to other developers or to yourself in future, but aren't visible to users.

- x

For any platform not listed, please see the compilation guidelines in the main repository, which can assist you in building for your own operating system and architecture.

Releases are [available over on itch.io](https://lichendust.itch.io/meander). Each release zip file corresponds to the checksums here.

1. Here, I don't mean Clippy popups that take you on a tour, or the act of reading the keybinding menu. I mean actual, wordless design decisions that enable the user to figure things out without reading or needing things pointed out. Some concepts are obviously too complex for this, but the basics of getting started in an app should be graspable by just looking around at the first working screen the user is presented with. ↩
2. This is especially important for libraries or compiler-installables, where something like Rust's Cargo or the Go mod proxy will swallow your mislabelled version and render it unfixable without burning the version number and Git tag. ↩