proposal: cmd/doc: add "// Unstable:" prefix convention #34409
Comments
|
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. |
|
Maybe this has already been suggested somewhere, but would it not be better to support all tags of the form |
|
@beoran, I think the point of this proposal is the semantics, not the syntax: if we want to know how to identify an unstable API we must “bless” a specific tag as having that meaning, or else no one will know to add it. |
|
@codyoss, that still seems like an appropriate role for build constraints..? You can start with the API guarded by some tag (perhaps |
Yes, I agree. I should have been more clear in my response. I was more so responding to proposal being linked and the fact that it solves the "what if I want to remove it" and not the "I want to promote it" issue. For this reason I don't think that the proposal, #30639, should necessarily be a blocker for this issue. |
|
Build constraints don't work well when you have an API that you wish to declare unstable externally but use internally to implement stable features. Now that we have type aliases, this may be possible now, but type aliases still leave godoc as a total mess. |
|
@dfawley, you can certainly use If you want, you can even apply build tags such that the That said, it usually should not be necessary: you can usually define the types in the unstable public package as their own struct wrapper types rather than aliases. (That also prevents new exported methods added to the
That seems like one or more issues that should be filed separately. |
|
@dfawley: |
Yes, especially in this scenario. Consider a package with an extensive experimental API. Users would have to navigate back and forth between two (or more) packages: one containing the symbols they are allowed to access, and another one (or more) containing the usage documentation, struct fields, interface methods, etc. And where one experimental function accepts an experimental struct as a parameter: package internal
type MyInterface interface {
MyFunc(MyStruct) error
}
type MyStruct struct {
...
}package experimental
type MyInterface = internal.MyInterface
type MyStruct = internal.MyStructWhen reading the documentation for package experimental
type FooBar = internal.MyStructIn this contrived example, that is obviously bad, but it's possible something like this could end up happening in practice with good intentions behind it. The first workaround @bcmills mentions above works, but I really don't want to maintain two identical copies of an API. You could generate the //go:generate cp ../experimental_*.go .; sed -i '1s;^;// +build !unstable;' experimental_*.go...but this is pretty gross. And you have to manually maintain the Moveover, what library developer is realistically going to think to do all of this? The process for creating an experimental API should be simple, straightforward, and a pattern that is obvious or discoverable when the desire to create one arises. Not something that took several engineers debating for months to eventually concoct its final form. Almost nobody will do this. Instead they'll just add a comment, like we do in grpc-go today. |
|
That totally makes sense, and is something I have considered asking for before, probably best to make a new ticket for it, since it would be useful orthogonal to this issue. I will say that rust seems to have solved the alias problem in their docs, inlining them in a way that many times I do not know they are even aliases, but they also give vastly more control over what is and is not included. |
The general process for creating an experimental API is:
Or:
Or:
The extra work of defining forwarding wrappers only comes up as a concern for experimental APIs that simultaneously:
So, yeah: if you're doing something unusual (developing an experimental API, over the course of multiple releases, with public and internal-stable users), then you may need to do some extra work (such as maintaining forwarding declarations) in order to facilitate that. But that is (or ought to be) a rare case, not the default workflow for new APIs. |
Is this a suggestion or cannon? Can we get this written up in a faq, blog, or wiki page? I am unclear how discoverable this (open) issue is.
What are best practices for build constraints?
Are you suggesting that the
|
|
Not saying they are right, or right for Go, but other languages(libraries) do support the idea of unstable APIs via annotation/comment. Specifically I am thinking of Guava's Beta annotation. |
Neither? It is a description of approaches that can be followed today by combining mechanisms that are each already fairly well-established in Go.
Perhaps that's the thing to decide here? IMO you can't go wrong with a per-feature build constraint, but a catchall
I am not suggesting the I am suggesting one of:
|
First, annotations are not comments, since they are available at runtime. IIUC, there is nothing congruent in go. While I agree that docs are more convenient, the discussion here seems to conclude that they are not enough. I would advocate for people ALSO putting details about the expected duration of experimental symbols in godoc, especially for prereleases intended for testing. That being said, you highlight a good point: once we define a convention here, godoc/gddo/pkgsite all need to be able to display or warn users about experimental symbols. |
Considering that so many packages ignore or go their own way for experimental features, I think that a documented canonical solution is necessary, even if you can derive these principles from existing documentation.
Agreed. I think there will always be a place for custom build tags, but having a convention will make the interface easier to use. I strongly prefer
Sorry for misunderstanding. I am happy to exclude this from the proposal, unless someone passionate can advocate for it.
Yeah, I have a few major version bumps that I have done with |
I think a single build tag is OK provided there is tooling support. There needs to be a way to prevent accidentally including unstable code, which would otherwise happen all the time:
|
Can you be more concrete on what you would like wrt "tooling support". I agree it would be very helpful, but this could be a warning during
I would make the argument that using the This speaks to your tooling comment, but displaying a warning in |
|
A tool that wrote every unstable symbol (or even just package) to stdout would be sufficient. Then the output could be dumped to a file included in the PR, and changes would show up as diffs. |
|
That is how I use |
|
Marking on hold until #30639 is decided, per #34409 (comment). |
|
Placed on hold. |
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: