github.com/spotify/syslog-redirector-golang@v0.0.0-20140320174030-4859f03d829a/doc/go1compat.html (about) 1 <!--{ 2 "Title": "Go 1 and the Future of Go Programs", 3 "Path": "/doc/go1compat" 4 }--> 5 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> 12 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> 20 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> 29 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> 36 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> 41 42 <h2 id="expectations">Expectations</h2> 43 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> 53 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> 60 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> 67 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> 76 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> 82 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 untagged 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 tagged 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 tagged struct 91 literals to remain compatible, although untagged 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 tagged notation. 96 </li> 97 98 <li> 99 Dot imports. If a program imports a standard package 100 using <code>import . "path"</code>, additional names defined in the 101 imported package in future releases may conflict with other names 102 defined in the program. We do not recommend the use of <code>import .</code> 103 outside of tests, and using it may cause a program to fail 104 to compile in future releases. 105 </li> 106 107 </ul> 108 109 <p> 110 Of course, for all of these possibilities, should they arise, we 111 would endeavor whenever feasible to update the specification, 112 compilers, or libraries without affecting existing code. 113 </p> 114 115 <p> 116 These same considerations apply to successive point releases. For 117 instance, code that runs under Go 1.2 should be compatible with Go 118 1.2.1, Go 1.3, Go 1.4, etc., although not necessarily with Go 1.1 119 since it may use features added only in Go 1.2 120 </p> 121 122 <p> 123 Features added between releases, available in the source repository 124 but not part of the numbered binary releases, are under active 125 development. No promise of compatibility is made for software using 126 such features until they have been released. 127 </p> 128 129 <p> 130 Finally, although it is not a correctness issue, it is possible 131 that the performance of a program may be affected by 132 changes in the implementation of the compilers or libraries upon 133 which it depends. 134 No guarantee can be made about the performance of a 135 given program between releases. 136 </p> 137 138 <p> 139 Although these expectations apply to Go 1 itself, we hope similar 140 considerations would be made for the development of externally 141 developed software based on Go 1. 142 </p> 143 144 <h2 id="subrepos">Sub-repositories</h2> 145 146 <p> 147 Code in sub-repositories of the main go tree, such as 148 <a href="http://code.google.com/p/go.net">code.google.com/p/go.net</a>, 149 may be developed under 150 looser compatibility requirements. However, the sub-repositories 151 will be tagged as appropriate to identify versions that are compatible 152 with the Go 1 point releases. 153 </p> 154 155 <h2 id="tools">Tools</h2> 156 157 <p> 158 Finally, the Go tool chain (compilers, linkers, build tools, and so 159 on) are under active development and may change behavior. This 160 means, for instance, that scripts that depend on the location and 161 properties of the tools may be broken by a point release. 162 </p> 163 164 <p> 165 These caveats aside, we believe that Go 1 will be a firm foundation 166 for the development of Go and its ecosystem. 167 </p>