diff --git a/doc/go1compat.html b/doc/go1compat.html new file mode 100644 index 00000000000..3804634f5da --- /dev/null +++ b/doc/go1compat.html @@ -0,0 +1,157 @@ + + +
+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. +
+ ++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. +
+ ++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.). +
+ ++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. +
+ ++The APIs may grow, acquiring new packages and features, but not in +a way that breaks existing Go 1 code. +
+ ++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. +
+ ++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. +
+ ++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 +
+ ++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. +
+ ++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. +
+ ++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. +
+ ++Code in sub-repositories of the main go tree, such as +code.google.com/p/go.net, +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. +
+ ++Finally, the Go tool chain (compilers, linkers, build tools, and so +on) are 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. +
+ ++These caveats aside, we believe that Go 1 will be a firm foundation +for the development of Go and its ecosystem. +