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.

[benjaminjkraft]

Good documentation style to crib from: https://main--typescript-eslint.netlify.app/users/versioning/

[benjaminjkraft]

At this point I think what we are doing so far is fine:

• syntactic changes to the output are not breaking, if you are testing that the output matches you should expect to update that when you update genqlient
• breaking changes to the API or behavior of the generated code are breaking
• changes, including breaking API changes, to any double-underscore-prefixed names in the generated code, are not breaking (i.e. don't refer to these in your code); the same applies to any names from the graphql runtime package documented as "intended for the use of genqlient's generated code only"
• your version of the graphql runtime package must be the same or newer (and the same major version) as your version of the code-generator; that is, changes to the code-generator requiring the same version of the runtime package are not breaking, but changes to the runtime package which require changes to the code-generator are breaking
• I've been marking dropping Go versions as breaking, but I think people don't really do that? Or at least, they don't cut new major versions.