Figure out, and document, what semver means for us

[benjaminjkraft]

In particular, obviously it's a breaking change if we change the signature of an exported symbol, like graphql.Client or generate.Main. But are these breaking changes?

The first question is: do we want to treat as breaking a change to the code-generator such that the new generated code has the same API but different implementation? If you have a test to require that go generate ./... doesn't make any changes, this will break that test, and that test is a reasonable thing you might want to have. But I think realistically there's no way we can treat that as a breaking change, since probably half our commits, including plenty of bugfixes, will change some generated code you might have.

The second question is: what if the new generated code has a breaking change in its API? This is only a breaking change once you run go generate ./.... I think in many cases we will want to treat it as a breaking change; certainly if we, say, change a type-name or the query-method signature! But what if we, make a change that's non-breaking if you use genqlient the expected way, but is breaking if you, say, use those structs for random other stuff? We'll want to see how much of an issue that might be for us, and document whatever we intend clearly. (This is extra true if you put your own code in the same package as the generated code, in which case there's nothing to stop you from calling internal helpers like __unmarshalWhateverType, which we definitely don't intend to be public API.)

Of course we don't need to figure this out perfectly until we cut a v1.0.0; until then we can just try our best and see what happens as we go.

Another issue is what code-generator versions are compatible with what runtime-library versions, but I suspect that will be a simpler issue.

[benjaminjkraft]

One thing to look at is what other codegen libraries do. There aren't a ton that aren't 0.x and have reasonable usage, but from what I can find:

• gojson has had few changes since v1 but I think this one is breaking in both senses
• sqlboiler has definitely had changes to in the first sense, but I think not in the second sense, although it's hard to tell for sure
• squirrel seems to have straight-up breaking library API changes
• gowrap has had several changes in the first sense, I'm having trouble finding any recent ones in the second sense In general I feel that aligns with what I wrote above: the first sense is fine, the second we should try to minimize but we can see what's reasonable.