Release v0.16.0

[BigLep]

Note: as part of doing this release, we'll develop a release issue SOP.

Things we'll document:

• Even vs Odd releases: https://gist.github.com/warpfork/98d2f4060c68a565e8ad18ea4814c25f

[warpfork]

Approximate SOP:

• (in practice: remind myself what I do for a release by looking at the last git tag, heh)
• Pick the next version name.
  • Version names are dotted numbers (vX.Y.Z) and they go up. (We've been using WarpVer, which is all but indistinguishable from SemVer, except we also try to use even numbers to say "this should be chill".)
• Update the CHANGELOG.md file.
  • Make a new h3 heading with the version name.
  • Slide any bullet points in the "recent changes" heading down to there.
  • Groom through the git history for other changes and make notes for them. (We aren't even close to consistently updating the changelog as we go; arguably unfortunate, but certainly true; dealwithit.jpg.)
    • I find this easiest to do by doing git log -- something like git log --all --graph --date-order --abbrev-commit --decorate --oneline, scrolling down to the last release, and then going back up.
    • If you can include links to the github PRs in the changelog, in case they have relevant data or discussion that's not in the commit, that's great. (If I have to dig too far to rediscover them, I give up quickly. Hopefully it's just obvious in the git log -- github's merge features do this. (The rebase features don't, irksomely...))
      • It's okay to be slapdash about this. More link connectivity is better. But ultimately, anything that's important should've been massaged into the commit message logs or the content diff itself, so github PR links are "nice to have" only, IMO.
  • Summarize. Curate.
    • Ideally the changelog spends more prose on important things and less prose on unimportant things.
    • Ideally the changelog includes very literal suggestions on how to migrate, when necessary. (Sed expressions are great.)
    • Ordering? Eh. I usually go roughly oldest-at-the-bottom (same order git-log gives things out). But I group things that seem related for better reading. Season to taste. I don't think there's an expectation of, or any real value to, a strict order here. It's a summary.
    • Sometimes I add links to ipld.io/glossary/#relevant-term to inline phrases in the changelog, if I think it'll be markedly helpful in context. (Also "season to taste".)
    • This usually takes a couple hours (shouldn't take more more... but don't rush it either).
  • Add "special thanks to" folks if possible!
    • Include yourself! (It's not obvious who the speaker is in half the places this text will end up, so it's not tooting your own horn, it's just being accurate.)
    • Include other people you can think of, too, even if they don't show up in the git changelog! (Code reviews, design discussions, specs work -- all those are significant contributions too!)
• Commit.
• Tag. (e.g. git tag vX.Y.Z && git push --tags. Or do it in the github UI.)
• Make a github release, in the github UI.
  • Copy the same material from the changelog file into the release, and ship it.
  • (The purpose of this is almost entirely just to generate an email.)
• Optional: Protocol Labs has an email list called shipped@ which people tend to actually read; it may be worth sending a short note there. (Shame that list isn't open; it'd probably be widely useful.)
• Optional: maybe shoot a quick message into the Matrix/Discord chatter.
  • Linking to the github release should be enough, and/or remind people there's a changelog file in the repo root. (Maybe link to the changelog file? Similar end effect.)
  • I tend to share at least one thing I'm personally superpsyched about, but Season To Taste.

(P.S.: Things we don't have: some other marketing push like blog and twitter (maybe this would be nice).)

For point releases (i.e. the Z in vX.Y.Z is increasing): I don't reliably bother to do any of this. In practice, a point release generally means someone bothered me to make a release for the purpose of having a release, rather than anything I'd consider a communicatively useful reason. I usually backfill the h3 tags for point releases the next time I bother to do the changelog grooming work for a major minor (which is really major, because major is always zero) release, because I find it easier to do this work in batches, and just don't bother to do the github release / email blast. If someone else doing these wants to do the work at the time, more power to ya.

[warpfork]

Done: https://github.com/ipld/go-ipld-prime/releases/tag/v0.16.0