docs: add RELEASE.md

[guseggert]

No description provided.

[codecov]

Codecov Report

Merging #266 (d375724) into main (a12deee) will increase coverage by 0.03%.
The diff coverage is n/a.

❗ Current head d375724 differs from pull request most recent head 5325008. Consider uploading reports for the commit 5325008 to get more accurate results

@@            Coverage Diff             @@
##             main     #266      +/-   ##
==========================================
+ Coverage   47.88%   47.91%   +0.03%     
==========================================
  Files         273      273              
  Lines       33186    33186              
==========================================
+ Hits        15890    15901      +11     
+ Misses      15619    15609      -10     
+ Partials     1677     1676       -1     

see 9 files with indirect coverage changes

[BigLep]

Good stuff Gus. Thanks for getting this critical stuff documented!

Somethings came to mind while reviewing this. I'm happy to verbal if that's quicker for you:

1. Will we do release on Friday? I assume yes because this isn't a binary. Any production deployment is handled by others and that is there responsibility to make decisions on when to build and deploy. Lets document.
2. What about giving credit to contributors? I'm thinking about the contributor portion of mkreleaselog.
3. What's the mechanism for Kubo updating? (I realize that is Kubo's problem, not Boxo, but it's coming to mind, in part because we're opening PR's in Kubo. I assume this gets swept up in the usual "how does Kubo update its dependencies" bucket)
4. Are we going to use any other announcement channels about the release? How about discuss.ipfs.tech and blog (linking to release)?
5. I assume there isn't the complexity in this release to warrant having an accompanying PR where we make changes to the release process as we go (like we do with Kubo: https://www.notion.so/pl-strflt/Kubo-Release-Process-5a5d066264704009a28a79cff93062c4?pvs=4#b154fdedd1a04cdbb6b0056d654b4329 )

[BigLep]

Move this under docs/ ? Not sure the best move here, but I was thinking the FAQ.md should be there per #260

[BigLep]

I looked at how this played out in 0.8. My comments/thoughts are linked below for completeness. I also made a couple of small suggestions based on some of this too.

#264 (comment)
#264 (review)
#257 (comment)

[guseggert]

Seems like nobody is happy w/ the changelog, we probably need to talk with @galargh about what to do there since it impacts tooling.

Bringing together the various comments:

• A section to call out breaking changes
• Links to issues/PRs
• Auto-generated "Contributors" list
• "Motivation" section for each change (like "TLDR why should I care?")

[BigLep]

Seems like nobody is happy w/ the changelog, we probably need to talk with @galargh about what to do there since it impacts tooling.

• A section to call out breaking changes

Is everything under "removed" a breaking change (and maybe some things under "changed")? Maybe we just make sure those are at the top? I was thinking we could even add a "Breaking Change" section header and put "Removed" under there, but maybe the better way is to add a legend here and have something like 🛠 (what we have used before) next to each line denoting a breaking change.

• Links to issues/PRs

This should just come during the changelog addition. I see they're doing that in https://keepachangelog.com/en/1.0.0/

• Auto-generated "Contributors" list

I don't know the full history on this, but seems like a good OSS practice to give credit to folks who contribute. That said, maybe we can just scope it to those who are contributing to Boxo directly rather than all the dependencies?

• "Motivation" section for each change (like "TLDR why should I care?")

I don't think we need this in general. Ideally providing a link to the related issue is good. I was wondering if we need a tldr about the release because looking at #264 I don't think we're really calling out as well for folks about the big picture things that they may care about. Maybe this would have been done better if we were requiring a changelog addition/change per PR. Maybe too we can use another emoji (✨ ?) to highlight things people should pay attention to especially (and that's also our signal to make sure our descriptive text is particularly useful then).

I like the guiding principle of "Changelogs are for humans, not machines"

So maybe have something at the top of our changelog (which also gets pasted into the "release") like:

---

We follow semver.  More notes about versioning and our release policies are [here](link to release policies doc).

Legend:
* 🛠 - BREAKING CHANGE.  Action is required if you use this functionality.  
* ✨ - Noteworthy change to aware of.

[BigLep]

2023-04-11 maintainer conversation:

It's clear the steps we're going to do to resolve this...

1. A legend will be used to denote breaking changes and features someone should pay attention to.
2. We will link to informative issues or PRs that give more details on a change.
3. We will get all release policy functionality together (either in this document, they readme, or the FAQ)
4. Giving credit to contributors will happen in followup work: Give credit to contributors during a release #276

• Release v0.8.0 #264 (comment) was handled with an update to the release process.
• Release v0.8.0 #264 (review) items were covered above
• Release v0.8.0 #257 (comment) can be done later. For now we'll just have a single changelog.md file.

That said, we didn't answer these questions during our call:

1. Will we do a release on Friday? I assume yes because this isn't a binary. Any production deployment is handled by others and that is there responsibility to make decisions on when to build and deploy. Lets document.
   • @BigLep thought: I can go either way here. If we release on Friday, folks will get a dependabot announcement then. It make sense just to hold to not doing releases on Friday.
2. Are we going to use any other announcement channels about the release? How about discuss.ipfs.tech and blog (linking to release)?
   • @BigLep : discuss.ipfs.tech and blog link seem reasonable to me. We can own our destiny on both (e.g., Update Kubo: v0.19.1 ipfs-blog#554 ).

[guseggert]

Will we do a release on Friday? I assume yes because this isn't a binary

Yeah I'd like to do this until we discover a reason not to, I think by default that we should bias towards release velocity.

discuss.ipfs.tech seems fine. Do we have any data on how many people view release blog entries or click the links?

[guseggert]

Opened #277 to write down how to publish a blog entry in the release process

[BigLep]

Thanks @guseggert ! Looking good to me. I made some small suggestions, but feel free to ship whenever at this point.