X-Git-Url: https://git.josue.xyz/?a=blobdiff_plain;ds=inline;f=.config%2Fcoc%2Fextensions%2Fcoc-go-data%2Ftools%2Fpkg%2Fmod%2Fgolang.org%2Fx%2Ftools%40v0.0.0-20201028153306-37f0764111ff%2Finternal%2Fapidiff%2FREADME.md;fp=.config%2Fcoc%2Fextensions%2Fcoc-go-data%2Ftools%2Fpkg%2Fmod%2Fgolang.org%2Fx%2Ftools%40v0.0.0-20201028153306-37f0764111ff%2Finternal%2Fapidiff%2FREADME.md;h=0000000000000000000000000000000000000000;hb=3ddadb3c98564791f0ac36cb39771d844a63dc91;hp=3d9576c28663a6bf3aa7aa35ad65f794d1801698;hpb=5f797af6612ed10887189b47a1efc2f915586e59;p=dotfiles%2F.git diff --git a/.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools@v0.0.0-20201028153306-37f0764111ff/internal/apidiff/README.md b/.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools@v0.0.0-20201028153306-37f0764111ff/internal/apidiff/README.md deleted file mode 100644 index 3d9576c2..00000000 --- a/.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools@v0.0.0-20201028153306-37f0764111ff/internal/apidiff/README.md +++ /dev/null @@ -1,624 +0,0 @@ -# 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.