You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
203 lines
7.0 KiB
203 lines
7.0 KiB
<!--{
|
|
"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>
|