proposal: doc: add "exp" build tag convention

[carnott-snap]

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: ...

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.

ExperimentalFoo

On 2019-11-13T18:49:13Z Russ Cox <@rsc> wrote:

[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 #34409 Experimental prefixes are cumbersome and do not have a clean graduation path to stability.

[rsc]

Closing as duplicate of #34409, since both have the same goal and we should have one mechanism, not two.

[jba]

@rsc Can we then retitle #34409, since the current title says it's only about a comment convention.