chore: add additional todos in the "change checklist"

[ramfox]

Description

In order to be better prepared for releases, we are trying to "front load" more work on understanding the effects of breaking changes in our downstream dependencies. Part of this is to remind folks to take a look at the downstream dependencies when they make a breaking change, and file an issue (or they have capacity), open a PR on how to deal with those breaking changes in that dependency.

The PR template looks like this now:

Description

Breaking Changes

Notes & open questions

Change checklist

• Self-review.
• Documentation updates following the style guide, if relevant.
• Tests if relevant.
• All breaking changes documented.
  • List all breaking changes in the above "Breaking Changes" section.
  • Open an issue or PR on any number0 repos that are affected by this breaking change. Give guidance on how the updates should be handled or do the actual updates themselves. The major ones are:
    • quic-rpc
    • iroh-gossip
    • iroh-blobs
    • dumbpipe
    • sendme

[github-actions]

Documentation for this PR has been generated and is available at: https://n0-computer.github.io/iroh/pr/3180/docs/iroh/

Last updated: 2025-02-17T16:30:32Z

[github-actions]

Netsim report & logs for this PR have been generated and is available at: LOGS
This report will remain available for 3 days.

Last updated for commit: 93036cd

[flub]

Oh, you're daring to add explicit instructions! I had given up on this :D

[divagant-martian]

I'm not following what

Open an issue or PR on any affected downstream dependency repos

means here. This should be clear even for newcomers and first time contributors.

Also, is this really a subtask of "document all breaking changes?

[ramfox]

Also, is this really a subtask of "document all breaking changes?

I think yes! It's literally about documenting breaking changes, including adding instructions about how breaking changes are going to effect our other repos.

[divagant-martian]

I tried to think how this work and now I'm a bit less convinced, so sorry for holding this up. Maybe at the end you are right anyway.

What's the case for a release that has multiple breaking changes? is there one issue per repo per breaking change then? What should these issues contain as content? I would think they have the "how to update" but it's that not what simply documenting the breaking changes here should achieve? I know these dependants are those we own but I would think our breaking changes description should be good enough to allow any dependant to update correctly

[matheus23]

I know these dependants are those we own but I would think our breaking changes description should be good enough to allow any dependant to update correctly

I think this is a good point, and it's true. That said, I think there's something else that should be documented in the issues that are opened in the downstream repositories.

Going back to one of the original issues that motivated this change (as far as I know): The change in #3110

The PR is a little short on breaking changes (i.e. it doesn't mention going from re-exporting quinn::Connection to our own Connection struct), but in the end this is not what was the problem.
The problem was the implications for e.g. iroh-blobs, where we used to assume that you can provide it with either a quinn::Connection from quinn, or from iroh. Even if the breaking changes were listed fully, this upgrade would still be harder for iroh-blobs, so ideally should've gotten more attention ahead of release day.

So the point of creating the issue is not to mention the breaking change in another place - but to take the architecture of the repository that needs to be updated into account and come up with an upgrade plan - or even propose a concrete upgrade with a PR.

[flub]

So the point of creating the issue is not to mention the breaking change in another place - but to take the architecture of the repository that needs to be updated into account and come up with an upgrade plan - or even propose a concrete upgrade with a PR.

Yeah, I interpret this as: create a draft PR with a patch to the branch with your breaking change. If it's simple it's fine. If all things break you'll notice. At this point you can either try and solve it or describe what needs to be done in an issue I guess. But at least it'll be more visible.

As part of this I'm also guessing that the main branch of those repos will often end up living with a patch pointing to the iroh main branch in between releases.

But I'm making a lot more assumptions then is being described. I understand the template tries to strike a balance with keeping it light though.

[ramfox]

Yeah, I interpret this as: create a draft PR with a patch to the branch with your breaking change. If it's simple it's fine. If all things break you'll notice. At this point you can either try and solve it or describe what needs to be done in an issue I guess. But at least it'll be more visible.

This is my intension.