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: doc: document api compatibility #34600

Open
urandom2 opened this issue Sep 29, 2019 · 9 comments
Open

proposal: doc: document api compatibility #34600

urandom2 opened this issue Sep 29, 2019 · 9 comments

Comments

@urandom2
Copy link
Contributor

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

@bcmills
Copy link
Contributor

bcmills commented Sep 30, 2019

CC @jayconrod @thepudds @jadekler @tbpg

@jeanbza
Copy link
Member

jeanbza 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
Copy link
Contributor

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

@urandom2
Copy link
Contributor Author

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.

@carnott-snap
Copy link

Is any additional information required, or is this proposal on Hold, but not correctly labelled? It appears to have missed the past few proposal review meetings: #33502.

@ianlancetaylor ianlancetaylor added this to Incoming in Proposals (old) Feb 5, 2020
@urandom2
Copy link
Contributor Author

urandom2 commented Mar 9, 2020

I do not think this proposal has any opposition. Can we at least green light the initiative, and final location, so that somebody (happy to oblige) can get started compiling a single document?

@Merovius
Copy link
Contributor

Merovius commented Apr 7, 2021

Why are the existing documents not enough? In particular, apidiff seems to document an automatically checked notion of API compatibility and is maintained by the Go team, AFAICT. Why is this not exactly "the single document" you want?

Why do Modules need to be treated separately? To me, it seems fairly obvious that a module is compatible, as long as all its non-internal packages are compatible (in a sense defined by whatever notion of API compatibility you prefer).

@Merovius
Copy link
Contributor

Merovius commented Apr 7, 2021

To be more specific: I don't really understand what the problem you are trying to solve is. On the one hand, you seem to perceive it as a problem that there are too many documents describing compatibility - on the other, you seem to be suggesting to write another.

IMO the Go 1 compatibility guarantee is a statement about the Go project with a notion of compatibility that is appropriate for this project - that doesn't mean it should be considered a recommendation for how third party Go code should handle compatibility. You also mention the spec (which, AFAICT, doesn't mention compatibility in this sense at all). And a blog post about modules, which, IMO, is not the same as documentation (in particular, blog posts are not normally living documents that are kept updated, whereas documentation is). Lastly, you mention a third party tool, over which we have no control.

So, the only reasonable documentation of API compatibility in the list, as far as I can tell, is the one provided by apidiff. Which brings back to the question of "why is that not exactly what you want?" :)

@thepudds
Copy link
Contributor

thepudds commented Apr 8, 2021

Note that this blog entry attempts to talk about how to keep your APIs compatible as well:

https://blog.golang.org/module-compatibility

I think that was published after this issue was filed.

@rsc rsc changed the title proposal: document api compatibility proposal: doc: document api compatibility Aug 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Incoming
Development

No branches or pull requests

9 participants