proposal: cmd/doc: add "// Unstable:" prefix convention #34409
Comments
Due to the lack of stability guarantees provided for service Server and Client interfaces, as hightlighted in #2318 and #3024, this change adds a godoc line that both warns users and suggests the canonical workaround. The structure of the godoc text is styled after an open proposal, golang/go#34409, thus may need to be changed, but attempts to play well with the tooling ecosystem, as was done for deprecated with golang/go#10909.
Due to the lack of stability guarantees provided for service Server and Client interfaces, as hightlighted in grpc/grpc-go#2318 and grpc/grpc-go#3024, this change adds a godoc line that both warns users and suggests the canonical workaround. The structure of the godoc text is styled after an open proposal, golang/go#34409, thus may need to be changed, but attempts to play well with the tooling ecosystem, as was done for deprecated with golang/go#10909.
Due to the lack of stability guarantees provided for service Server and Client interfaces, as hightlighted in grpc/grpc-go#2318 and grpc/grpc-go#3024, this change adds a godoc line that both warns users and suggests the canonical workaround. The structure of the godoc text is styled after an open proposal, golang/go#34409, thus may need to be changed, but attempts to play well with the tooling ecosystem, as was done for deprecated with golang/go#10909.
|
cc @jba We've talked about having apidiff ignore changes to definitions that are annotated like this. I imagine it would be useful for other tools as well. |
|
What are next steps for getting approval for this proposal? |
|
@carnott-snap I don't think this really needs to go through the formal proposal process. It's something we agree on and discussed already as part of the apidiff and gorelease design. I think the next step would be for this to be implemented in This should be documented somewhere, but I'm not sure where yet. We should have documentation on preparing a release, linked from https://golang.org/doc/. That should basically be a checklist, and gorelease can refer to it in error messages. These stability comments could be mentioned there. About the specifics on the comments: I agree that |
Is it worth getting this closed/tagged as
Does Google want to own the dev work? If not, I am happy to contribute.
Long term it would be nice to mentioning this as part of the module release docs item in #33637. But for now, I think we can follow the lead that
Totally agree, may be worth getting a wider audience, but one acceptable word seems better than two perfect ones.
IIRC, doc comments rules will not allow it to be the first paragraph, though |
rsc
changed the title
rsc
changed the title
|
Adding "// Unstable:" has a much larger effect than "// Deprecated:". "// Unstable" is much more invasive. It says "even though you might think otherwise, I reserve the right to change the types/code here in the future or delete it entirely and break your uses." If you don't see the comment, it's a very big deal: you upgrade and your code breaks. The big question is not what the comment syntax should be but whether we want to bless this kind of user-hurting behavior at all. An alternative would be to develop experimental changes like this on explicitly experimental version tags (v1.6.1-unstable, for example), keeping the unstable code completely out of the stable tag. Another alternative would be to put the name into the defined symbols, like "mypkg.UnstableFoo", like we did for types like testing.InternalBenchmark (before internal directories). It's impossible to miss the Unstable when it's in the name. We should very carefully consider what the right way is to let package authors experiment without hurting users. A simple comment does not seem like enough. (I realize that the idea is tools would surface the comment etc but then that's just more mechanism on top, whereas versions or symbol names that explicitly say unstable reuse existing mechanism.) |
Note that there are already at least a few examples of unstable definitions in the standard library. For example, consider:
|
|
As another data point, there are also several symbols in the These definitions are only meant to be called by generated code that is tightly coupled with the However, some definitions like the ones Bryan mentioned may have their own definition of compatibility. According to apidiff, changing the value of an integer constant is an incompatible change because it may be used as an array length. Using |
|
@rsc I'm not sure what the next step is. It doesn't sound like the proposal committee has accepted or rejected this. What information would be useful in making a decision? |
As a data point. In the protobuf module, there are several types or functions explicitly marked as being for internal use only. However, they must be exported in order for generated code to access them. We reserve the right to change those APIs with the caveat that we don't break existing usages that were properly generated by protoc-gen-go. Whether this convention is adopted or not, this type of sharp edge already exists. In v1 the sharp edge is awful since the internal functions is placed alongside public functions in the |
|
@jayconrod I think that what might be helpful is a reason why you can't use names like |
|
@ianlancetaylor My expectation is that I'm planning to ship an experimental version of |
|
Sorry if this is an unhelpful comment, but the cmd/api tool in the standard library does have a way to suppress false positives, for the kinds of examples that @bcmills cites above. See the files in https://golang.org/api/ . |
|
|
I didn't mean anything special about the exact word |
|
The (IMO pretty major) downside of putting words like (It's the same reason we don't distinguish between |
|
It's much better to use branches for experimental features. This makes 2 worlds(stable and experimental) independent and reduces possible mistakes for the user. As Russ mentioned above: comment is too weak to protect user from incorrect usage. Extending previous comment by Bryan: In other words: comments or unstable api increases code entropy which increases code maintainability. |
|
I built this proposal around documentation to make adoption less invasive. This was partially based on experience with the protobuf libraries, where they define custom compatibility guarantees. I agree condoning unstable interfaces is troublesome, but many projects require it, and I wanted a canonical way to label/identify it, both for users and tooling. It may be helpful to isolate the use cases that exist for instability: (please correct me if I left anything out or if this is a false trichotomy)
I think we all agree that we want stable packages, but even the standard library is developing experimental or long term unstable features. Most examples use documentation to signal their stability, so this seemed intuitive and canonical. What emphasis should be placed on supporting existing patterns, as opposed to preventing undesirable behaviour? Outstanding concerns:
|
The proposal committee's job is to help steer a discussion toward consensus, not to decide on their own. It sounds like there is no consensus here yet. I wrote a lot about this topic at https://research.swtch.com/proposals-experiment. It's very important that people know they are using experimental features. Otherwise we run the risk of hitting the situation Rust did where everyone was on "unstable". I have the same concern about the "exp" build tag in #35704: it's too easy to lapse into where everything uses this. Actually the build tag may be worse, since if any dependency super far down uses exp, you have to do the same. So basically everyone will have to use it. |
|
I would like to be clear about the purposes of the two tickets being discussed:
My concern is that the current state of things is not good. Major tools are actively developing and releasing unstable features, by
Would a
I have worked with Rust myself and do not see this today. Are there any lessons we can learn from their experiences? My understanding was that they had a lot of important features that needed to be stabilised, e.g. async, and that finally unlocking things from the nightly compiler was the fix.
Since #35704 is trying to solve a different problem, would you mind continuing the discussion there? I broke it out partially because I saw two heterogeneous problems (pre-release and custom compatibility) that felt like they may should be solved differently. |
|
Yes, it would be slightly better. I'm a user of both etcd and grpc, and if this would have been the case, my projects could just have imported grpc in two different major versions. An old one for etcd and a new one for grpc. Though, an "experimental" tag would only increase the visibility. It wouldn't keep etcd from using such an API voluntarily. And if such a tag doesn't propagate, user's of etcd wont see the problem with the library they're importing. |
|
Nobody has any perfect answers here, at least not so far. The choices are "bad" and "less bad". |
Why would an API compatible with gRPC v1.2 necessarily imply an implementation older than v5.3? I think the protobuf migration is a good example here: the old API ( |
An It's true that build tags used in that way become viral, in that anyone who wants to use an API guarded by the tag also has to set the tag, but that's an intrinsic property of unstable APIs: depending on an unstable API is necessarily viral. |
That's fair, but etcd users also wouldn't have been broken by changes to gRPC if the etcd authors had read and abided by the gRPC godocs, which very clearly labeled this package as unreliable. This is where things went wrong, and what this FR is hoping can be prevented in the future. You had asked:
...and the above was my example for you. |
|
@dfawley How would an explicit "unstable" comment convention be any better than the comment that was already there? That is, you have a clear example that relying on comments doesn't work. But "unstable", as proposed here, is just another comment. |
|
@ianlancetaylor My answer to your question is that "unstable" can be propagated to downstream users by tools that recognize the convention. It's important to be clear what you mean by "work" in "relying on comments doesn't work." If you mean "prevent etcd from relying on experimental API," I've argued that nothing would work since etcd made a deliberate choice to use an API they knew was experimental. The best we can do is warn downstream users that they are indirectly consuming experimental API, and a machine-readable convention can help with that. |
|
Using auto completion in editors or cut'n'paste from web sites people end up depending on APIs without ever actually reading the documentation for them. An experimental tag that is tool readable could both be used to downrank experimental completions as well as warn users when they start depending on experimental features. |
|
I'd strongly encourage naming experimental APIs in a fashion that clearly conveys the experimental status, exactly to make it the experimental nature clear in contextless code snippets.
|
|
@neild Names don't necessarily propagate, and propagation is the harder problem. Please see my comment above, the paragraph starting "What if grpc had named their package |
|
I really like the idea of have this comment based vs symbol based. If I created an experimental API and that surface turned out to work just as well as intended I think it is great for users that they don't have to make any code changes to continue using the feature. Whereas if I had named my function ExperimentalFoo and stabilized it all users of the api will need to update their code when they upgrade the dependency. |
|
If we feel that propagation (read: virality) is important, the best option we have today is build tags. Sure, this will require some tooling support, like js, so that symbols will be surfaced even if you do not provide the correct tags, but the alternative is that we have to do a lot of tooling support to ensure that a symbol prefix, or comment propagates through code paths. I would rather trust the compiler for this. I also personally prefer an EDIT: Since only the comments of this ticket talk to the build flag approach, feel free to review #35704 for my proposal. |
|
@neild Naming does not work, because there are lots of ways that function and type names are hidden from you in normal code, even without transitive dependancies being considered. If we made the naming an actual convention that tools can detect, it might be useful, otherwise it is barely better than the plain documentation form. This also comes into play if you start talking about gorelease, which is supposed to tell you if you are making breaking changes, which would also need to make a decision about experimental APIs. @codyoss I don't think the experimental naming thing is a big hurdle as you stabilize, you can leave the experimental symbol there aliasing the now real symbol anyway, and ideally we will have good migration tools for this kind of thing. Keeping the name different also has some advantages (eg try out two signatures at the same time as different experiment names and pick a winner based on usage). One real downside is if you are trying to see if an API is truly ergonomic, which it might not be with a long experimental name. |
|
If there is a tool that understands the concept of "unstable", would all APIs under a v0 module automatically be considered unstable since it not stable according to semver?
Since a vast number of modules are still at v0, wouldn't this functionally make nearly every module essentially "unstable" since it depends transitively on a v0 module somewhere? |
|
That is not a consideration that I put into this proposal, but you make a good claim: one should not not rely upon 0.x.z symbols any more than the |
As others have said, the difference is visibility and propagation. If there is a standard, tooling can detect it, which has value. There are other options, which may be worth fleshing out.
IMO there needs to be granularity if a build tag is used. Otherwise using one experimental/unstable feature for your own purposes opens the door to all unstable features used by anyone. One aspect the proposal here may not fully appreciate about this situation is that the "poisoning" of using an unstable API from a foreign package happens at the package level. I.e. if the unstable API is removed, the entire package which references it breaks, meaning a transitive declaration needs to happen at the package level (or conditional compilation is required). There are also module-level scope considerations. If I call an unstable function in another package within the same module, that shouldn't make the package that uses it unstable, since, as the maintainer of the module, I can ensure it always continues to work, even if the unstable function is removed. However, if the unstable function in the other package is unstable because it calls an unstable API from a foreign module, then it would be transitive.
This is a tangent, but this is a problem that has concerned me for some time. We should really get v1 releases for at least the Go-owned packages that everyone relies upon, e.g. "x": https://github.com/golang/sys/releases |
I actually see this as a feature. Presumably tooling, godoc/pkgsite, could highlight any experimental tooling, but if you look to the rust community, they have a thriving nightly compiler that allows people to test out and prototype pre-release libraries. This even involves alpha libraries, using other alpha libraries in addition to alpha language features. It does lock people into this ecosystem until all the features they need are stabilised, but it is clear that you are running experimental. Back in Go, you could even write an adaptor for the interface you want and tag that Are you suggesting a convention like
IMO, this is actually something that build tags solve. If we hide all the experimental code behind
This smells like an opportunity to use
Yeah, tagging the extended standard library has been a long time coming, see #21324. That being said, there is a graceful way to encourage this: we could define a Go version, say 1.17, after which |
|
@jba I'm not seeing how an "unstable" comment propagates in a way that is actually useful. Can you give an example? Thanks. |
Sort of? But you can still have a stable API even if the implementation is unstable, as long as you promise that you will respond to breaking changes in your dependencies by reimplementing the functionality without changing your own exported API. (Note that you cannot fix a breaking change in that manner if your API directly returns or accepts an unstable type.) But tools today can already use
Yes. Nearly every module really is unstable in that sense, especially given #21324. (This check is called out explicitly as the second bullet-point in #26420.) |
|
@ianlancetaylor Imagine that the experimental grpc package had a tool-aware "unstable" comment, and etcd did exactly what they did, using that package without any mention of its being experimental. Now someone comes along and wants to use the etcd package. They look at its documentation and see an indication that the package imports an unstable package. Perhaps when they look at the doc for How is any of that useful? That user has information to make a decision. They may go ahead anyway, but avoid releasing a v1 version of their product. Or they may look around for an alternative, stable implementation of the same functionality. Or they may choose to ignore the problem, but at least their importers will have that information. |
|
@jba It sounds like you are saying this:
Does that sound right? How deep should it look? If a package exports a type with methods, some of those methods can refer to unstable APIs. Should any use of that type be considered unstable? Is this a plausible check to run? I don't think we could do anything similar in "go vet", except perhaps as an optional check that people would have to opt into. |
|
@ianlancetaylor That's about right, but you make it sound like we'd do all that at serving time. When we process a module M (in the background), we'd check our DB for unstable packages on its build list and store that information with M. We'd also have to go in the other direction, updating modules that depended on M. But that will be a very small number because we check the index every minute or so, so not too many modules can have downloaded M in that time.
I think I'm convinced that instability is always a property of packages, as argued above. So yes. But that's not really a question that an informational tool like pkg.go.dev has to answer. We just have to point out that the package you're looking at depends on unstable packages or symbols, with as fine a grain as we think helpful and can reasonably compute, and let you decide what that means for your project. |
|
I want to call out that this seems like a lot of work, and we have to do it for pkgsite, godoc, and gorelease, plus the community has to implement (or integrate) it for every ide/linter. I would also like to call out that even |
|
I think the tooling work is also an argument in favor of using a build tag. We already need to do some work to support common build tags ( |
@bcmills How does pkg.go.dev handle methods/functions that only appear in a file with a build tag today? |
|
I just wanted to throw in my 2 cents from what is being done in some of the cloud client library packages today.
I will note that we do float a v0.X.0 so this is not a huge issue for us, but even so we try our best to treat the code as if it were a v1.X.X. I believe that experimentation is vital for any long tail project that wants to keep evolving. Excited to see how this and some of the other mentioned proposals evolve. |
|
I was envisioning it very differently, I would make a simple checker that complains if you reference an unstable symbol from a stable one. |
@bcmills That issue seems somewhat related, but should evolve to include custom constraints if it is to be considered a viable alternative. I think an option like this seems fine as long as tooling like auto-complete and godoc support it is well. |
|
@ianthehat What forces the authors to surface the instability? |
What did you see today?
Many projects have different stability guarantees for the exported symbols in a package. Others rely on generated code that cannot, or will not, give stability guarantees. As such, most authors will document this pre-release or instability in doc strings, but the syntax and conventions are all over the place.
The standard library likes to reference the
Go compatibility promiseorGo 1 compatibility guidelines, since it is bound by them, however these do not work well for community packages. Other terms likenon-portableandEXPERIMENTALare descriptive and well explained inunsafeandsyscall/jsrespectively.Some community libraries have used terms like
// Alpha: ...,// Beta: ..., and// Unstable: ..., which work as well. There could be an argument for not releasing pre-release features on a stable branch, but other times like with the proto client/serverinterfaces, instability is a guarantee that must be worked around.What would you like to see?
Similar to
// Deprecated: ..., I would like to see the stabilization of supported comment tags for unstable symbols.They support the same three formats that same three formats that deprecation has.
These tags should also allow such symbols to be excluded from the
goreleasetool.A single tag should be sufficient:
// Unstable: ...When interacting with released, finalized symbol that cannot or will not be stabilized, the description can provide stability workarounds, alternatives, or what guarantees should be expected.
When interacting with pre-release features, a proposed timeline can be given or alternatives for customers requiring stability guarantees.
What did not work?
The
// Alpha: ...and// Beta: ...options looked promising, since they would only be used for temporary instability as part of the release process. The two terms overload one another (what is the difference between alpha, beta, and// PreRelease: ...?), leading to confusion. Furthermore, the programmatic benefits of knowing an API will stabilize in a future release is not that useful, "is it unstable now?" is more important.The
// Experimental: ...syntax used by the standard library implies the notion that the feature will eventually be stabilized. This further overloads it with alpha, beta, etc. and does not fit the needs of the above gRPC interfaces.The
// NonPortable: ...syntax is too domain specific tounsafeto make sense for purely semantic changes to packages. It makes sense forunsafe, but does not generalizeThe text was updated successfully, but these errors were encountered: