"Fossies" - the Fresh Open Source Software Archive

Member "go/doc/go1compat.html" (9 Sep 2020, 7216 Bytes) of package /windows/misc/go1.14.9.windows-386.zip:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!--{
    2     "Title": "Go 1 and the Future of Go Programs",
    3     "Path":  "/doc/go1compat"
    4 }-->
    6 <h2 id="introduction">Introduction</h2>
    7 <p>
    8 The release of Go version 1, Go 1 for short, is a major milestone
    9 in the development of the language. Go 1 is a stable platform for
   10 the growth of programs and projects written in Go.
   11 </p>
   13 <p>
   14 Go 1 defines two things: first, the specification of the language;
   15 and second, the specification of a set of core APIs, the "standard
   16 packages" of the Go library. The Go 1 release includes their
   17 implementation in the form of two compiler suites (gc and gccgo),
   18 and the core libraries themselves.
   19 </p>
   21 <p>
   22 It is intended that programs written to the Go 1 specification will
   23 continue to compile and run correctly, unchanged, over the lifetime
   24 of that specification. At some indefinite point, a Go 2 specification
   25 may arise, but until that time, Go programs that work today should
   26 continue to work even as future "point" releases of Go 1 arise (Go
   27 1.1, Go 1.2, etc.).
   28 </p>
   30 <p>
   31 Compatibility is at the source level. Binary compatibility for
   32 compiled packages is not guaranteed between releases. After a point
   33 release, Go source will need to be recompiled to link against the
   34 new release.
   35 </p>
   37 <p>
   38 The APIs may grow, acquiring new packages and features, but not in
   39 a way that breaks existing Go 1 code.
   40 </p>
   42 <h2 id="expectations">Expectations</h2>
   44 <p>
   45 Although we expect that the vast majority of programs will maintain
   46 this compatibility over time, it is impossible to guarantee that
   47 no future change will break any program. This document is an attempt
   48 to set expectations for the compatibility of Go 1 software in the
   49 future. There are a number of ways in which a program that compiles
   50 and runs today may fail to do so after a future point release. They
   51 are all unlikely but worth recording.
   52 </p>
   54 <ul>
   55 <li>
   56 Security. A security issue in the specification or implementation
   57 may come to light whose resolution requires breaking compatibility.
   58 We reserve the right to address such security issues.
   59 </li>
   61 <li>
   62 Unspecified behavior. The Go specification tries to be explicit
   63 about most properties of the language, but there are some aspects
   64 that are undefined. Programs that depend on such unspecified behavior
   65 may break in future releases.
   66 </li>
   68 <li>
   69 Specification errors. If it becomes necessary to address an
   70 inconsistency or incompleteness in the specification, resolving the
   71 issue could affect the meaning or legality of existing programs.
   72 We reserve the right to address such issues, including updating the
   73 implementations. Except for security issues, no incompatible changes
   74 to the specification would be made.
   75 </li>
   77 <li>
   78 Bugs. If a compiler or library has a bug that violates the
   79 specification, a program that depends on the buggy behavior may
   80 break if the bug is fixed. We reserve the right to fix such bugs.
   81 </li>
   83 <li>
   84 Struct literals. For the addition of features in later point
   85 releases, it may be necessary to add fields to exported structs in
   86 the API. Code that uses unkeyed struct literals (such as pkg.T{3,
   87 "x"}) to create values of these types would fail to compile after
   88 such a change. However, code that uses keyed literals (pkg.T{A:
   89 3, B: "x"}) will continue to compile after such a change. We will
   90 update such data structures in a way that allows keyed struct
   91 literals to remain compatible, although unkeyed literals may fail
   92 to compile. (There are also more intricate cases involving nested
   93 data structures or interfaces, but they have the same resolution.)
   94 We therefore recommend that composite literals whose type is defined
   95 in a separate package should use the keyed notation.
   96 </li>
   98 <li>
   99 Methods. As with struct fields, it may be necessary to add methods
  100 to types.
  101 Under some circumstances, such as when the type is embedded in
  102 a struct along with another type,
  103 the addition of the new method may break
  104 the struct by creating a conflict with an existing method of the other
  105 embedded type.
  106 We cannot protect against this rare case and do not guarantee compatibility
  107 should it arise.
  108 </li>
  110 <li>
  111 Dot imports. If a program imports a standard package
  112 using <code>import . "path"</code>, additional names defined in the
  113 imported package in future releases may conflict with other names
  114 defined in the program.  We do not recommend the use of <code>import .</code>
  115 outside of tests, and using it may cause a program to fail
  116 to compile in future releases.
  117 </li>
  119 <li>
  120 Use of package <code>unsafe</code>. Packages that import
  121 <a href="/pkg/unsafe/"><code>unsafe</code></a>
  122 may depend on internal properties of the Go implementation.
  123 We reserve the right to make changes to the implementation
  124 that may break such programs.
  125 </li>
  127 </ul>
  129 <p>
  130 Of course, for all of these possibilities, should they arise, we
  131 would endeavor whenever feasible to update the specification,
  132 compilers, or libraries without affecting existing code.
  133 </p>
  135 <p>
  136 These same considerations apply to successive point releases. For
  137 instance, code that runs under Go 1.2 should be compatible with Go
  138 1.2.1, Go 1.3, Go 1.4, etc., although not necessarily with Go 1.1
  139 since it may use features added only in Go 1.2
  140 </p>
  142 <p>
  143 Features added between releases, available in the source repository
  144 but not part of the numbered binary releases, are under active
  145 development. No promise of compatibility is made for software using
  146 such features until they have been released.
  147 </p>
  149 <p>
  150 Finally, although it is not a correctness issue, it is possible
  151 that the performance of a program may be affected by
  152 changes in the implementation of the compilers or libraries upon
  153 which it depends.
  154 No guarantee can be made about the performance of a
  155 given program between releases.
  156 </p>
  158 <p>
  159 Although these expectations apply to Go 1 itself, we hope similar
  160 considerations would be made for the development of externally
  161 developed software based on Go 1.
  162 </p>
  164 <h2 id="subrepos">Sub-repositories</h2>
  166 <p>
  167 Code in sub-repositories of the main go tree, such as
  168 <a href="//golang.org/x/net">golang.org/x/net</a>,
  169 may be developed under
  170 looser compatibility requirements. However, the sub-repositories
  171 will be tagged as appropriate to identify versions that are compatible
  172 with the Go 1 point releases.
  173 </p>
  175 <h2 id="operating_systems">Operating systems</h2>
  177 <p>
  178 It is impossible to guarantee long-term compatibility with operating
  179 system interfaces, which are changed by outside parties.
  180 The <a href="/pkg/syscall/"><code>syscall</code></a> package
  181 is therefore outside the purview of the guarantees made here.
  182 As of Go version 1.4, the <code>syscall</code> package is frozen.
  183 Any evolution of the system call interface must be supported elsewhere,
  184 such as in the
  185 <a href="//golang.org/x/sys">go.sys</a> subrepository.
  186 For details and background, see
  187 <a href="//golang.org/s/go1.4-syscall">this document</a>.
  188 </p>
  190 <h2 id="tools">Tools</h2>
  192 <p>
  193 Finally, the Go toolchain (compilers, linkers, build tools, and so
  194 on) is under active development and may change behavior. This
  195 means, for instance, that scripts that depend on the location and
  196 properties of the tools may be broken by a point release.
  197 </p>
  199 <p>
  200 These caveats aside, we believe that Go 1 will be a firm foundation
  201 for the development of Go and its ecosystem.
  202 </p>