[mirror] Go Tools.zip

# 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 s