You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
During the discussion of #34409, it became clear that stronger conventions around signalling instability should be used when writing Go. Currently there are many ways to signal to users that a given symbol is unstable.
// Experimental: ...
package analysis // import "golang.org/x/tools/go/analysis"
type SuggestedFix struct {
// ... all fields elided ...
}
A SuggestedFix is a code change associated with a Diagnostic that a user can
choose to apply to their code. Usually the SuggestedFix is meant to fix the
issue flagged by the diagnostic. TextEdits for a SuggestedFix should not
overlap. TextEdits for a SuggestedFix should not contain edits for other
packages. Experimental: This API is experimental and may change in the
future.
EXPERIMENTAL
package js // import "syscall/js"
Package js gives access to the WebAssembly host environment when using the
js/wasm architecture. Its API is based on JavaScript semantics.
This package is EXPERIMENTAL. Its current scope is only to allow tests to
run, but not yet to provide a comprehensive API for users. It is exempt from
the Go compatibility promise.
[P]ut the name into the defined symbols, like "mypkg.UnstableFoo", like we did for types like testing.InternalBenchmark (before internal directories).
What would you like to see?
Experimental symbols should be gated by the exp build flag: e.g.
// +build exp,js,wasm// Package js ...package js
Using build flags requires users opt in to such instability symbols. It gives a transparent forward compatible upgrade path: simply remove the build tag and users continuing to provid it will still consume the symbol. It allows authors to release features without cluttering their external api, since these experimental symbols will simply not show up. Finally, it is pure convention, so it does not require any changes to the language, and exp is not a magical build tag to the toolchain. This flag is also granular and can be used for a whole package, or just some symbols.
What did not work?
Scope
This proposal is specific to alpha, beta, pre-release, or experimental features that are not intended for general consumption. It does not work well with other use cases described in #34409, custom compatibility and internal interfaces.
Prior art
None of the current approaches clearly signal to users that the symbols are experimental, and as noted in #34409Experimental prefixes are cumbersome and do not have a clean graduation path to stability.
The text was updated successfully, but these errors were encountered:
What did you see today?
During the discussion of #34409, it became clear that stronger conventions around signalling instability should be used when writing Go. Currently there are many ways to signal to users that a given symbol is unstable.
// Experimental: ...
EXPERIMENTAL
ExperimentalFoo
On 2019-11-13T18:49:13Z Russ Cox <@rsc> wrote:
What would you like to see?
Experimental symbols should be gated by the
exp
build flag: e.g.Using build flags requires users opt in to such instability symbols. It gives a transparent forward compatible upgrade path: simply remove the build tag and users continuing to provid it will still consume the symbol. It allows authors to release features without cluttering their external api, since these experimental symbols will simply not show up. Finally, it is pure convention, so it does not require any changes to the language, and
exp
is not a magical build tag to the toolchain. This flag is also granular and can be used for a whole package, or just some symbols.What did not work?
Scope
This proposal is specific to alpha, beta, pre-release, or experimental features that are not intended for general consumption. It does not work well with other use cases described in #34409, custom compatibility and internal interfaces.
Prior art
None of the current approaches clearly signal to users that the symbols are experimental, and as noted in #34409
Experimental
prefixes are cumbersome and do not have a clean graduation path to stability.The text was updated successfully, but these errors were encountered: