diff options
Diffstat (limited to 'doc/go1compat.html')
-rw-r--r-- | doc/go1compat.html | 202 |
1 files changed, 0 insertions, 202 deletions
diff --git a/doc/go1compat.html b/doc/go1compat.html deleted file mode 100644 index a5624ef5f6..0000000000 --- a/doc/go1compat.html +++ /dev/null @@ -1,202 +0,0 @@ -<!--{ - "Title": "Go 1 and the Future of Go Programs", - "Path": "/doc/go1compat" -}--> - -<h2 id="introduction">Introduction</h2> -<p> -The release of Go version 1, Go 1 for short, is a major milestone -in the development of the language. Go 1 is a stable platform for -the growth of programs and projects written in Go. -</p> - -<p> -Go 1 defines two things: first, the specification of the language; -and second, the specification of a set of core APIs, the "standard -packages" of the Go library. The Go 1 release includes their -implementation in the form of two compiler suites (gc and gccgo), -and the core libraries themselves. -</p> - -<p> -It is intended that programs written to the Go 1 specification will -continue to compile and run correctly, unchanged, over the lifetime -of that specification. At some indefinite point, a Go 2 specification -may arise, but until that time, Go programs that work today should -continue to work even as future "point" releases of Go 1 arise (Go -1.1, Go 1.2, etc.). -</p> - -<p> -Compatibility is at the source level. Binary compatibility for -compiled packages is not guaranteed between releases. After a point -release, Go source will need to be recompiled to link against the -new release. -</p> - -<p> -The APIs may grow, acquiring new packages and features, but not in -a way that breaks existing Go 1 code. -</p> - -<h2 id="expectations">Expectations</h2> - -<p> -Although we expect that the vast majority of programs will maintain -this compatibility over time, it is impossible to guarantee that -no future change will break any program. This document is an attempt -to set expectations for the compatibility of Go 1 software in the -future. There are a number of ways in which a program that compiles -and runs today may fail to do so after a future point release. They -are all unlikely but worth recording. -</p> - -<ul> -<li> -Security. A security issue in the specification or implementation -may come to light whose resolution requires breaking compatibility. -We reserve the right to address such security issues. -</li> - -<li> -Unspecified behavior. The Go specification tries to be explicit -about most properties of the language, but there are some aspects -that are undefined. Programs that depend on such unspecified behavior -may break in future releases. -</li> - -<li> -Specification errors. If it becomes necessary to address an -inconsistency or incompleteness in the specification, resolving the -issue could affect the meaning or legality of existing programs. -We reserve the right to address such issues, including updating the -implementations. Except for security issues, no incompatible changes -to the specification would be made. -</li> - -<li> -Bugs. If a compiler or library has a bug that violates the -specification, a program that depends on the buggy behavior may -break if the bug is fixed. We reserve the right to fix such bugs. -</li> - -<li> -Struct literals. For the addition of features in later point -releases, it may be necessary to add fields to exported structs in -the API. Code that uses unkeyed struct literals (such as pkg.T{3, -"x"}) to create values of these types would fail to compile after -such a change. However, code that uses keyed literals (pkg.T{A: -3, B: "x"}) will continue to compile after such a change. We will -update such data structures in a way that allows keyed struct -literals to remain compatible, although unkeyed literals may fail -to compile. (There are also more intricate cases involving nested -data structures or interfaces, but they have the same resolution.) -We therefore recommend that composite literals whose type is defined -in a separate package should use the keyed notation. -</li> - -<li> -Methods. As with struct fields, it may be necessary to add methods -to types. -Under some circumstances, such as when the type is embedded in -a struct along with another type, -the addition of the new method may break -the struct by creating a conflict with an existing method of the other -embedded type. -We cannot protect against this rare case and do not guarantee compatibility -should it arise. -</li> - -<li> -Dot imports. If a program imports a standard package -using <code>import . "path"</code>, additional names defined in the -imported package in future releases may conflict with other names -defined in the program. We do not recommend the use of <code>import .</code> -outside of tests, and using it may cause a program to fail -to compile in future releases. -</li> - -<li> -Use of package <code>unsafe</code>. Packages that import -<a href="/pkg/unsafe/"><code>unsafe</code></a> -may depend on internal properties of the Go implementation. -We reserve the right to make changes to the implementation -that may break such programs. -</li> - -</ul> - -<p> -Of course, for all of these possibilities, should they arise, we -would endeavor whenever feasible to update the specification, -compilers, or libraries without affecting existing code. -</p> - -<p> -These same considerations apply to successive point releases. For -instance, code that runs under Go 1.2 should be compatible with Go -1.2.1, Go 1.3, Go 1.4, etc., although not necessarily with Go 1.1 -since it may use features added only in Go 1.2 -</p> - -<p> -Features added between releases, available in the source repository -but not part of the numbered binary releases, are under active -development. No promise of compatibility is made for software using -such features until they have been released. -</p> - -<p> -Finally, although it is not a correctness issue, it is possible -that the performance of a program may be affected by -changes in the implementation of the compilers or libraries upon -which it depends. -No guarantee can be made about the performance of a -given program between releases. -</p> - -<p> -Although these expectations apply to Go 1 itself, we hope similar -considerations would be made for the development of externally -developed software based on Go 1. -</p> - -<h2 id="subrepos">Sub-repositories</h2> - -<p> -Code in sub-repositories of the main go tree, such as -<a href="//golang.org/x/net">golang.org/x/net</a>, -may be developed under -looser compatibility requirements. However, the sub-repositories -will be tagged as appropriate to identify versions that are compatible -with the Go 1 point releases. -</p> - -<h2 id="operating_systems">Operating systems</h2> - -<p> -It is impossible to guarantee long-term compatibility with operating -system interfaces, which are changed by outside parties. -The <a href="/pkg/syscall/"><code>syscall</code></a> package -is therefore outside the purview of the guarantees made here. -As of Go version 1.4, the <code>syscall</code> package is frozen. -Any evolution of the system call interface must be supported elsewhere, -such as in the -<a href="//golang.org/x/sys">go.sys</a> subrepository. -For details and background, see -<a href="//golang.org/s/go1.4-syscall">this document</a>. -</p> - -<h2 id="tools">Tools</h2> - -<p> -Finally, the Go toolchain (compilers, linkers, build tools, and so -on) is under active development and may change behavior. This -means, for instance, that scripts that depend on the location and -properties of the tools may be broken by a point release. -</p> - -<p> -These caveats aside, we believe that Go 1 will be a firm foundation -for the development of Go and its ecosystem. -</p> |