Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.
Sign upproposal: document api compatibility #34600
Comments
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
+1, seems good to have. This seems like something that should be a spec, which apidiff (cc @jba) and related guides reference. What do y'all think? |
This comment has been minimized.
This comment has been minimized.
It's pretty hard to pin down a definition of compatibility that everyone can agree on (see Hyrum's Law). I agree that we should have some canonical documentation on the subject though. |
This comment has been minimized.
This comment has been minimized.
I have always thought of this as compile time compatibility, since runtime compatibility is hard if not impossible, as called out in the apidiff document. I think targeting does it compile is acheivable and apidiff is close if not exactly the package spec I would publish. |
Background
Currently there are four official definitions for api compatibility0123, as well as others offered by the community4. It should be noted that some of these definitions target package compatibility, where other target module compatibility, and some are experimental, while others have been constant since go1. Unfortunately, they each disagree on at least a few minor points in their definitions of compatibility. This lack of an official stance and single vision for compatibility has led to confusion and uncertainty among the community.
Proposal
In some official capacity, publish documentation both package and module compatibility guarantees. This should involve a package level definition, such as the
apidiff
definition2, and module definition, which can borrow heavily from the former.Footnotes
0] https://golang.org/doc/go1compat
1] https://blog.golang.org/publishing-go-modules#TOC_3.
2] https://go.googlesource.com/exp/+/master/apidiff/README.md
3] https://golang.org/ref/spec
4] https://github.com/bradleyfalzon/apicompat