decide about output compatibility guarantees

[josharian]

The secondary consideration for cutting a v1.0 of this package is deciding about output compatibility.

Given exactly the same inputs, do we guarantee the same outputs over time?

Upsides to output compatibility:

• Lets people use output in golden tests.
• Acknowledges Hyrum's Law.

Downsides to output compatibility:

• Severely limits bug fixes, optimizations, etc.
• May force major version upgrades v2.0 much earlier than otherwise.
• Slows down development by raising the threshold for releases.

I'm very torn. Opinions, @mvdan? (Or anyone else?)

[mvdan]

Lets people use output in golden tests.

They can if they simply pin the version via go.mod/go.sum. I'm not convinced that this is helpful.

Sure, they might have to update golden testdata files if they update the version of pkg/diff, but I think that's fine. Realistically, we wouldn't do that many output-breaking changes, and downstreams wouldn't have to upgrade at every chance if they prefer less churn.

Acknowledges Hyrum's Law.

I think we should be OK as long as we clarify in the docs whether or not reproducibility is part of certain input/output APIs.

Perhaps people start complaining in the future, and perhaps then we decide to raise this proposal again. I'm hoping that won't happen.

Severely limits bug fixes, optimizations, etc.

I think this is a dealbreaker for diff packages. I'd personally pick the diff library that does the best job, not the one that has stable output between versions. The competition with other diff tools/libraries is already pretty fierce, so I don't think we need to give ourselves a disadvantage.

[josharian]

OK, I'm convinced. No compatibility guarantees for output. Thanks!

The competition with other diff tools/libraries is already pretty fierce, so I don't think we need to give ourselves a disadvantage.

I don't know why I find this amusing, but I do.