docs: add breaking change interop release process

[aschmahmann]

@achingbrain lmk if this looks right to you. @lidel and I went through this yesterday as a proposed way to do the interop dance versioning dance.

This is dependent on some of the changes from #387 being extracted and landing in master so that it's really easy to change which commit of go/js-ipfs we're building against in CI.

[achingbrain]

There seem like quite a lot of steps in this dance, and I think the js monorepo will complicate matters as using a git commit as a version signifier isn't always enough, for example when the branch the commit refers to has changes in multiple modules in the monorepo you'll need to somehow make those changes available.

Longer term perhaps we could take a similar approach to the one we use with the interface-ipfs-core tests - whereby all tests become opt-in and you add a config file to your project that defines which tests you want to run and/or otherwise skip for the current version/project/environment.

I'm also a little unconvinced of the utility of having CI running on this repo given any changes made to it would usually accompany a PR to either go-ipfs or js-ipfs so you're always going to have to juggle unreleased code which almost seems more trouble than it's worth. What do you think?

[aschmahmann]

@achingbrain unless I'm missing something not running CI in this repo only ends up removing step 2 and everything else remains the same. Is step 2 that painful? It should hopefully be as simple as changing a config line from v0.X.Y to asdf1324.

and I think the js monorepo will complicate matters as using a git commit as a version signifier isn't always enough

I can't speak to this if this is problematic, if so it might be worth reconsidering. I'd hope that there's some way (commit hashes, branch names, etc.) that you could build and test unrelease JS code. @lidel any thoughts here?

I'm also a little unconvinced of the utility of having CI running on this repo given any changes made to it would usually accompany a PR to either go-ipfs or js-ipfs so you're always going to have to juggle unreleased code which almost seems more trouble than it's worth. What do you think?

Having CI here seems useful if we're going to modify or add new tests. Otherwise every PR to this repo requires a corresponding temporary PR in go/js-ipfs that targets the interop repo so we can verify things pass. It also means go/js-ipfs will have to set the special EXEC env vars to point at each other if there's a coordinated breaking change which seems more confusing than doing it here.

[lidel]

and I think the js monorepo will complicate matters as using a git commit as a version signifier isn't always enough

Correct.

I had to write a bunch of code to test pubsub changes (#387) in go-ipfs, js-ipfs-http-server and js-ipfs-http-client, and i think would be good to upstream this glue code somehow, so the next person that has to "break and fix js/go interop" of some command does not have to spend a day figuring out how to correctly link to a package from js-ipfs monorepo.

the utility of having CI running on this repo given any changes made to it would usually accompany a PR to either go-ipfs or js-ipfs

Maybe I jumped the gun in #387 and we don't need to keep master green at all times?
If we never had green CI on this repo during those breaking changes, and just merged stuff that passed locally, then we could simplify the list (see suggestion inline)

[lidel]

If we want to simplify and have go-ipfs and js-ipfs green, instead of this repo, then maybe:

Suggested change

	1. Get branches of go-ipfs and js-ipfs working together in interop locally using environment variables to point at the local versions
	2. In this repo make a branch containing the interop changes as well as setting the go/js-ipfs commit hashes to be used by CI. Merge to master.
	3. Update go-ipfs and js-ipfs branches to use interop/master instead of whatever is released
	4. Release go and js-ipfs (not necessarily together) and after each is released (or RC'd) bump interop to use the release instead of the commit hash
	5. Release interop
	6. Bump go and js-ipfs to use released interop instead of master
	1. Get branches of go-ipfs and js-ipfs working together in interop locally using environment variables to point at the local versions
	2. In this repo make a branch containing the interop changes. CI won't pass with release versions of go/js-ipfs, but it is ok, as long (1) passed locally. Merge to master.
	3. Update go-ipfs and js-ipfs branches to use a commit from interop/master instead of whatever is released. The ipfs/interop test in their CI should be green now.
	4. Release go and js-ipfs (not necessarily together) and after each is released (or RC'd) bump interop to use the release instead of the commit hash. This will fix CI in ipfs/interop repo.
	5. Release ipfs/interop when its CI is green again.
	6. Bump go and js-ipfs to use released interop instead of master

[aschmahmann]

Assuming no disastrous problems with the js monorepo I think making CI pass seems like the reasonable thing to do here and if it's as simple as changing a line from v0.X.Y -> abcd1234 then it's pretty simple as well.

In the go-ipfs v0.11.0 release alone there are 3 breaking changes that it's helpful to see fail and then fix individually (sharding, circuit-relay, pubsub). If we don't keep CI green here it puts a lot of pressure on reviewers to make sure when things work on their machines that it's not just on their machines due to some particular configuration or stray environment variable.

[lidel]

Ack. After thinking about it in context of go-ipfs 0.11 using interop/master in go-ipfs (rolling branch, instead of hardcoded revision) will make our merge fest easier.

[lidel]

Ack. After thinking about it in context of go-ipfs 0.11 using interop/master in go-ipfs (rolling branch, instead of hardcoded revision) will make our merge fest easier.

[github-actions]

🎉 This PR is included in version 8.0.9 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀