golang.org/x/exp@v0.0.0-20240506185415-9bf2ced13842/cmd/gorelease/testdata/internalcompat/README.txt (about)

     1  Modules example.com/internalcompat/{a,b} are copies. One could be a fork
     2  of the other. An external package p exposes a type from a package q
     3  within the same module.
     4  
     5  If gorelease ran apidiff on the two modules instead of on the individual
     6  packages, then it should not report differences between these packages. The types
     7  are distinct, but they correspond (in apidiff terminology), which is the
     8  important property when considering differences between modules. More
     9  specifically, the fully qualified type names are identical modulo the change
    10  to the module path.
    11  
    12  But at the time gorelease was written, apidiff did not support module
    13  comparison. If considered at the package level, the two packages
    14  example.com/internalcompat/a/p and example.com/internalcompat/b/p
    15  are incompatible, because the packages they refer to are different.
    16  
    17  So case 2 below would apply if whole modules were being diffed, but
    18  it doesn't here because individual packages are being diffed.
    19  
    20  There are three use cases to consider:
    21  
    22  1. One module substitutes for the other via a `replace` directive.
    23     Only the replacement module is used, and the package paths are effectively
    24     identical, so the types are not distinct.
    25  2. One module subsititutes for the other by rewriting `import` statements
    26     globally. All references to the original type become references to the
    27     new type, so there is no conflict.
    28  3. One module substitutes for the other by rewriting some `import` statements
    29     but not others (for example, those within a specific consumer package).
    30     In this case, the types are distinct, and even if there are no changes,
    31     the types are not compatible.