Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

proposal: document api compatibility #34600

Open
arnottcr opened this issue Sep 29, 2019 · 4 comments

Comments

@arnottcr
Copy link

@arnottcr arnottcr commented Sep 29, 2019

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

@gopherbot gopherbot added this to the Proposal milestone Sep 29, 2019
@bcmills

This comment has been minimized.

Copy link
Member

@bcmills bcmills commented Sep 30, 2019

@jadekler

This comment has been minimized.

Copy link
Contributor

@jadekler jadekler commented Sep 30, 2019

+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?

@jayconrod

This comment has been minimized.

Copy link
Contributor

@jayconrod jayconrod commented Sep 30, 2019

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.

Related #33637
Related #26420

@arnottcr

This comment has been minimized.

Copy link
Author

@arnottcr arnottcr commented Sep 30, 2019

It's pretty hard to pin down a definition of compatibility that everyone can agree on (see Hyrum's Law).

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.