diff options
Diffstat (limited to '')
-rw-r--r-- | dependencies/pkg/mod/golang.org/x/exp@v0.0.0-20220613132600-b0d781184e0d/apidiff/README.md | 624 |
1 files changed, 624 insertions, 0 deletions
diff --git a/dependencies/pkg/mod/golang.org/x/exp@v0.0.0-20220613132600-b0d781184e0d/apidiff/README.md b/dependencies/pkg/mod/golang.org/x/exp@v0.0.0-20220613132600-b0d781184e0d/apidiff/README.md new file mode 100644 index 0000000..3d9576c --- /dev/null +++ b/dependencies/pkg/mod/golang.org/x/exp@v0.0.0-20220613132600-b0d781184e0d/apidiff/README.md @@ -0,0 +1,624 @@ +# Checking Go Package API Compatibility + +The `apidiff` tool in this directory determines whether two versions of the same +package are compatible. The goal is to help the developer make an informed +choice of semantic version after they have changed the code of their module. + +`apidiff` reports two kinds of changes: incompatible ones, which require +incrementing the major part of the semantic version, and compatible ones, which +require a minor version increment. If no API changes are reported but there are +code changes that could affect client code, then the patch version should +be incremented. + +Because `apidiff` ignores package import paths, it may be used to display API +differences between any two packages, not just different versions of the same +package. + +The current version of `apidiff` compares only packages, not modules. + + +## Compatibility Desiderata + +Any tool that checks compatibility can offer only an approximation. No tool can +detect behavioral changes; and even if it could, whether a behavioral change is +a breaking change or not depends on many factors, such as whether it closes a +security hole or fixes a bug. Even a change that causes some code to fail to +compile may not be considered a breaking change by the developers or their +users. It may only affect code marked as experimental or unstable, for +example, or the break may only manifest in unlikely cases. + +For a tool to be useful, its notion of compatibility must be relaxed enough to +allow reasonable changes, like adding a field to a struct, but strict enough to +catch significant breaking changes. A tool that is too lax will miss important +incompatibilities, and users will stop trusting it; one that is too strict may +generate so much noise that users will ignore it. + +To a first approximation, this tool reports a change as incompatible if it could +cause client code to stop compiling. But `apidiff` ignores five ways in which +code may fail to compile after a change. Three of them are mentioned in the +[Go 1 Compatibility Guarantee](https://golang.org/doc/go1compat). + +### Unkeyed Struct Literals + +Code that uses an unkeyed struct literal would fail to compile if a field was +added to the struct, making any such addition an incompatible change. An example: + +``` +// old +type Point struct { X, Y int } + +// new +type Point struct { X, Y, Z int } + +// client +p := pkg.Point{1, 2} // fails in new because there are more fields than expressions +``` +Here and below, we provide three snippets: the code in the old version of the +package, the code in the new version, and the code written in a client of the package, +which refers to it by the name `pkg`. The client code compiles against the old +code but not the new. + +### Embedding and Shadowing + +Adding an exported field to a struct can break code that embeds that struct, +because the newly added field may conflict with an identically named field +at the same struct depth. A selector referring to the latter would become +ambiguous and thus erroneous. + + +``` +// old +type Point struct { X, Y int } + +// new +type Point struct { X, Y, Z int } + +// client +type z struct { Z int } + +var v struct { + pkg.Point + z +} + +_ = v.Z // fails in new +``` +In the new version, the last line fails to compile because there are two embedded `Z` +fields at the same depth, one from `z` and one from `pkg.Point`. + + +### Using an Identical Type Externally + +If it is possible for client code to write a type expression representing the +underlying type of a defined type in a package, then external code can use it in +assignments involving the package type, making any change to that type incompatible. +``` +// old +type Point struct { X, Y int } + +// new +type Point struct { X, Y, Z int } + +// client +var p struct { X, Y int } = pkg.Point{} // fails in new because of Point's extra field +``` +Here, the external code could have used the provided name `Point`, but chose not +to. I'll have more to say about this and related examples later. + +### unsafe.Sizeof and Friends + +Since `unsafe.Sizeof`, `unsafe.Offsetof` and `unsafe.Alignof` are constant +expressions, they can be used in an array type literal: + +``` +// old +type S struct{ X int } + +// new +type S struct{ X, y int } + +// client +var a [unsafe.Sizeof(pkg.S{})]int = [8]int{} // fails in new because S's size is not 8 +``` +Use of these operations could make many changes to a type potentially incompatible. + + +### Type Switches + +A package change that merges two different types (with same underlying type) +into a single new type may break type switches in clients that refer to both +original types: + +``` +// old +type T1 int +type T2 int + +// new +type T1 int +type T2 = T1 + +// client +switch x.(type) { +case T1: +case T2: +} // fails with new because two cases have the same type +``` +This sort of incompatibility is sufficiently esoteric to ignore; the tool allows +merging types. + +## First Attempt at a Definition + +Our first attempt at defining compatibility captures the idea that all the +exported names in the old package must have compatible equivalents in the new +package. + +A new package is compatible with an old one if and only if: +- For every exported package-level name in the old package, the same name is + declared in the new at package level, and +- the names denote the same kind of object (e.g. both are variables), and +- the types of the objects are compatible. + +We will work out the details (and make some corrections) below, but it is clear +already that we will need to determine what makes two types compatible. And +whatever the definition of type compatibility, it's certainly true that if two +types are the same, they are compatible. So we will need to decide what makes an +old and new type the same. We will call this sameness relation _correspondence_. + +## Type Correspondence + +Go already has a definition of when two types are the same: +[type identity](https://golang.org/ref/spec#Type_identity). +But identity isn't adequate for our purpose: it says that two defined +types are identical if they arise from the same definition, but it's unclear +what "same" means when talking about two different packages (or two versions of +a single package). + +The obvious change to the definition of identity is to require that old and new +[defined types](https://golang.org/ref/spec#Type_definitions) +have the same name instead. But that doesn't work either, for two +reasons. First, type aliases can equate two defined types with different names: + +``` +// old +type E int + +// new +type t int +type E = t +``` +Second, an unexported type can be renamed: + +``` +// old +type u1 int +var V u1 + +// new +type u2 int +var V u2 +``` +Here, even though `u1` and `u2` are unexported, their exported fields and +methods are visible to clients, so they are part of the API. But since the name +`u1` is not visible to clients, it can be changed compatibly. We say that `u1` +and `u2` are _exposed_: a type is exposed if a client package can declare variables of that type. + +We will say that an old defined type _corresponds_ to a new one if they have the +same name, or one can be renamed to the other without otherwise changing the +API. In the first example above, old `E` and new `t` correspond. In the second, +old `u1` and new `u2` correspond. + +Two or more old defined types can correspond to a single new type: we consider +"merging" two types into one to be a compatible change. As mentioned above, +code that uses both names in a type switch will fail, but we deliberately ignore +this case. However, a single old type can correspond to only one new type. + +So far, we've explained what correspondence means for defined types. To extend +the definition to all types, we parallel the language's definition of type +identity. So, for instance, an old and a new slice type correspond if their +element types correspond. + +## Definition of Compatibility + +We can now present the definition of compatibility used by `apidiff`. + +### Package Compatibility + +> A new package is compatible with an old one if: +>1. Each exported name in the old package's scope also appears in the new +>package's scope, and the object (constant, variable, function or type) denoted +>by that name in the old package is compatible with the object denoted by the +>name in the new package, and +>2. For every exposed type that implements an exposed interface in the old package, +> its corresponding type should implement the corresponding interface in the new package. +> +>Otherwise the packages are incompatible. + +As an aside, the tool also finds exported names in the new package that are not +exported in the old, and marks them as compatible changes. + +Clause 2 is discussed further in "Whole-Package Compatibility." + +### Object Compatibility + +This section provides compatibility rules for constants, variables, functions +and types. + +#### Constants + +>A new exported constant is compatible with an old one of the same name if and only if +>1. Their types correspond, and +>2. Their values are identical. + +It is tempting to allow changing a typed constant to an untyped one. That may +seem harmless, but it can break code like this: + +``` +// old +const C int64 = 1 + +// new +const C = 1 + +// client +var x = C // old type is int64, new is int +var y int64 = x // fails with new: different types in assignment +``` + +A change to the value of a constant can break compatibility if the value is used +in an array type: + +``` +// old +const C = 1 + +// new +const C = 2 + +// client +var a [C]int = [1]int{} // fails with new because [2]int and [1]int are different types +``` +Changes to constant values are rare, and determining whether they are compatible +or not is better left to the user, so the tool reports them. + +#### Variables + +>A new exported variable is compatible with an old one of the same name if and +>only if their types correspond. + +Correspondence doesn't look past names, so this rule does not prevent adding a +field to `MyStruct` if the package declares `var V MyStruct`. It does, however, mean that + +``` +var V struct { X int } +``` +is incompatible with +``` +var V struct { X, Y int } +``` +I discuss this at length below in the section "Compatibility, Types and Names." + +#### Functions + +>A new exported function or variable is compatible with an old function of the +>same name if and only if their types (signatures) correspond. + +This rule captures the fact that, although many signature changes are compatible +for all call sites, none are compatible for assignment: + +``` +var v func(int) = pkg.F +``` +Here, `F` must be of type `func(int)` and not, for instance, `func(...int)` or `func(interface{})`. + +Note that the rule permits changing a function to a variable. This is a common +practice, usually done for test stubbing, and cannot break any code at compile +time. + +#### Exported Types + +> A new exported type is compatible with an old one if and only if their +> names are the same and their types correspond. + +This rule seems far too strict. But, ignoring aliases for the moment, it demands only +that the old and new _defined_ types correspond. Consider: +``` +// old +type T struct { X int } + +// new +type T struct { X, Y int } +``` +The addition of `Y` is a compatible change, because this rule does not require +that the struct literals have to correspond, only that the defined types +denoted by `T` must correspond. (Remember that correspondence stops at type +names.) + +If one type is an alias that refers to the corresponding defined type, the +situation is the same: + +``` +// old +type T struct { X int } + +// new +type u struct { X, Y int } +type T = u +``` +Here, the only requirement is that old `T` corresponds to new `u`, not that the +struct types correspond. (We can't tell from this snippet that the old `T` and +the new `u` do correspond; that depends on whether `u` replaces `T` throughout +the API.) + +However, the following change is incompatible, because the names do not +denote corresponding types: + +``` +// old +type T = struct { X int } + +// new +type T = struct { X, Y int } +``` +### Type Literal Compatibility + +Only five kinds of types can differ compatibly: defined types, structs, +interfaces, channels and numeric types. We only consider the compatibility of +the last four when they are the underlying type of a defined type. See +"Compatibility, Types and Names" for a rationale. + +We justify the compatibility rules by enumerating all the ways a type +can be used, and by showing that the allowed changes cannot break any code that +uses values of the type in those ways. + +Values of all types can be used in assignments (including argument passing and +function return), but we do not require that old and new types are assignment +compatible. That is because we assume that the old and new packages are never +used together: any given binary will link in either the old package or the new. +So in describing how a type can be used in the sections below, we omit +assignment. + +Any type can also be used in a type assertion or conversion. The changes we allow +below may affect the run-time behavior of these operations, but they cannot affect +whether they compile. The only such breaking change would be to change +the type `T` in an assertion `x.T` so that it no longer implements the interface +type of `x`; but the rules for interfaces below disallow that. + +> A new type is compatible with an old one if and only if they correspond, or +> one of the cases below applies. + +#### Defined Types + +Other than assignment, the only ways to use a defined type are to access its +methods, or to make use of the properties of its underlying type. Rule 2 below +covers the latter, and rules 3 and 4 cover the former. + +> A new defined type is compatible with an old one if and only if all of the +> following hold: +>1. They correspond. +>2. Their underlying types are compatible. +>3. The new exported value method set is a superset of the old. +>4. The new exported pointer method set is a superset of the old. + +An exported method set is a method set with all unexported methods removed. +When comparing methods of a method set, we require identical names and +corresponding signatures. + +Removing an exported method is clearly a breaking change. But removing an +unexported one (or changing its signature) can be breaking as well, if it +results in the type no longer implementing an interface. See "Whole-Package +Compatibility," below. + +#### Channels + +> A new channel type is compatible with an old one if +> 1. The element types correspond, and +> 2. Either the directions are the same, or the new type has no direction. + +Other than assignment, the only ways to use values of a channel type are to send +and receive on them, to close them, and to use them as map keys. Changes to a +channel type cannot cause code that closes a channel or uses it as a map key to +fail to compile, so we need not consider those operations. + +Rule 1 ensures that any operations on the values sent or received will compile. +Rule 2 captures the fact that any program that compiles with a directed channel +must use either only sends, or only receives, so allowing the other operation +by removing the channel direction cannot break any code. + + +#### Interfaces + +> A new interface is compatible with an old one if and only if: +> 1. The old interface does not have an unexported method, and it corresponds +> to the new interfaces (i.e. they have the same method set), or +> 2. The old interface has an unexported method and the new exported method set is a +> superset of the old. + +Other than assignment, the only ways to use an interface are to implement it, +embed it, or call one of its methods. (Interface values can also be used as map +keys, but that cannot cause a compile-time error.) + +Certainly, removing an exported method from an interface could break a client +call, so neither rule allows it. + +Rule 1 also disallows adding a method to an interface without an existing unexported +method. Such an interface can be implemented in client code. If adding a method +were allowed, a type that implements the old interface could fail to implement +the new one: + +``` +type I interface { M1() } // old +type I interface { M1(); M2() } // new + +// client +type t struct{} +func (t) M1() {} +var i pkg.I = t{} // fails with new, because t lacks M2 +``` + +Rule 2 is based on the observation that if an interface has an unexported +method, the only way a client can implement it is to embed it. +Adding a method is compatible in this case, because the embedding struct will +continue to implement the interface. Adding a method also cannot break any call +sites, since no program that compiles could have any such call sites. + +#### Structs + +> A new struct is compatible with an old one if all of the following hold: +> 1. The new set of top-level exported fields is a superset of the old. +> 2. The new set of _selectable_ exported fields is a superset of the old. +> 3. If the old struct is comparable, so is the new one. + +The set of selectable exported fields is the set of exported fields `F` +such that `x.F` is a valid selector expression for a value `x` of the struct +type. `F` may be at the top level of the struct, or it may be a field of an +embedded struct. + +Two fields are the same if they have the same name and corresponding types. + +Other than assignment, there are only four ways to use a struct: write a struct +literal, select a field, use a value of the struct as a map key, or compare two +values for equality. The first clause ensures that struct literals compile; the +second, that selections compile; and the third, that equality expressions and +map index expressions compile. + +#### Numeric Types + +> A new numeric type is compatible with an old one if and only if they are +> both unsigned integers, both signed integers, both floats or both complex +> types, and the new one is at least as large as the old on both 32-bit and +> 64-bit architectures. + +Other than in assignments, numeric types appear in arithmetic and comparison +expressions. Since all arithmetic operations but shifts (see below) require that +operand types be identical, and by assumption the old and new types underly +defined types (see "Compatibility, Types and Names," below), there is no way for +client code to write an arithmetic expression that compiles with operands of the +old type but not the new. + +Numeric types can also appear in type switches and type assertions. Again, since +the old and new types underly defined types, type switches and type assertions +that compiled using the old defined type will continue to compile with the new +defined type. + +Going from an unsigned to a signed integer type is an incompatible change for +the sole reason that only an unsigned type can appear as the right operand of a +shift. If this rule is relaxed, then changes from an unsigned type to a larger +signed type would be compatible. See [this +issue](https://github.com/golang/go/issues/19113). + +Only integer types can be used in bitwise and shift operations, and for indexing +slices and arrays. That is why switching from an integer to a floating-point +type--even one that can represent all values of the integer type--is an +incompatible change. + + +Conversions from floating-point to complex types or vice versa are not permitted +(the predeclared functions real, imag, and complex must be used instead). To +prevent valid floating-point or complex conversions from becoming invalid, +changing a floating-point type to a complex type or vice versa is considered an +incompatible change. + +Although conversions between any two integer types are valid, assigning a +constant value to a variable of integer type that is too small to represent the +constant is not permitted. That is why the only compatible changes are to +a new type whose values are a superset of the old. The requirement that the new +set of values must include the old on both 32-bit and 64-bit machines allows +conversions from `int32` to `int` and from `int` to `int64`, but not the other +direction; and similarly for `uint`. + +Changing a type to or from `uintptr` is considered an incompatible change. Since +its size is not specified, there is no way to know whether the new type's values +are a superset of the old type's. + +## Whole-Package Compatibility + +Some changes that are compatible for a single type are not compatible when the +package is considered as a whole. For example, if you remove an unexported +method on a defined type, it may no longer implement an interface of the +package. This can break client code: + +``` +// old +type T int +func (T) m() {} +type I interface { m() } + +// new +type T int // no method m anymore + +// client +var i pkg.I = pkg.T{} // fails with new because T lacks m +``` + +Similarly, adding a method to an interface can cause defined types +in the package to stop implementing it. + +The second clause in the definition for package compatibility handles these +cases. To repeat: +> 2. For every exposed type that implements an exposed interface in the old package, +> its corresponding type should implement the corresponding interface in the new package. +Recall that a type is exposed if it is part of the package's API, even if it is +unexported. + +Other incompatibilities that involve more than one type in the package can arise +whenever two types with identical underlying types exist in the old or new +package. Here, a change "splits" an identical underlying type into two, breaking +conversions: + +``` +// old +type B struct { X int } +type C struct { X int } + +// new +type B struct { X int } +type C struct { X, Y int } + +// client +var b B +_ = C(b) // fails with new: cannot convert B to C +``` +Finally, changes that are compatible for the package in which they occur can +break downstream packages. That can happen even if they involve unexported +methods, thanks to embedding. + +The definitions given here don't account for these sorts of problems. + + +## Compatibility, Types and Names + +The above definitions state that the only types that can differ compatibly are +defined types and the types that underly them. Changes to other type literals +are considered incompatible. For instance, it is considered an incompatible +change to add a field to the struct in this variable declaration: + +``` +var V struct { X int } +``` +or this alias definition: +``` +type T = struct { X int } +``` + +We make this choice to keep the definition of compatibility (relatively) simple. +A more precise definition could, for instance, distinguish between + +``` +func F(struct { X int }) +``` +where any changes to the struct are incompatible, and + +``` +func F(struct { X, u int }) +``` +where adding a field is compatible (since clients cannot write the signature, +and thus cannot assign `F` to a variable of the signature type). The definition +should then also allow other function signature changes that only require +call-site compatibility, like + +``` +func F(struct { X, u int }, ...int) +``` +The result would be a much more complex definition with little benefit, since +the examples in this section rarely arise in practice. |