Forward Compatible Go Code

This is a creation in Article, where the information may have evolved or changed.

Liveblog by Linda Xie (@lindeexie)

Joe Tsai is a software Engineer on Google's Go team. He is a regular contributor to the Go standard library and other open source projects.

Gophers often use ' Go 1 compatibility ' as a magic phrase to indicate ' all present GO1 code'll always work on all FUT Ure Go1 releases. However, people is surprised to find out this running with the next version of Go sometimes causes build and test failure S.

Forward incompatible Go Code is caused by breakages due to the programmer. Forward incompatibility is also caused by breakages due to the toolchain, consisting of the Go compiler and standard Libra Ry.

Breakages due to the programmer

Breakages due to the programmer is the result of erroneous assumptions that come from relying on output stability, value comparability, Go runtime details.

Relying on output stability

Here are a list of packages that users incorrectly assume to be stable:

• Archive/{tar,zip}
• Compress/{flate,gzip,lzw,zlib}
• Encoding/{csv,gob,json,xml}
• Image/{gif,jpeg,png}
• Net/http
• Math/rand
• Sort

Had unstable output means that it was not safe to assume that the outputs was byte-for-byte identical. Assuming this can has huge implications. Below we have a type Record where one of the fields are a TimeStamp in seconds. An ID method returns theSHA-256 checksum of the JSON encoded struct to obtain a unique identifier for each Record. However, this is problematic because the JSON representation of the timestamp differs between releases. When this Record was stored in the database on one release of Go, it can not be properly retrieved in a later release since The ID has changed. Bugs of this nature is surprising and difficult to track down.

One-to-do-to-write your own struct marshalling where can guarantee output stability or use a Guarantees canonical serialisation, which have the property of output stability.

Relying on value comparability

Another category of assumptions programmers make is assuming and all values could be directly compared using the equality O Perator. Several types that is generally not safe to directly compare is:

• Time. Time
• Errors
• Reflect. Value
• Any types you don ' t own

Below is an example of the recording of a monotonic clock to the time type which provides more precise measurements of E Lapsed time. By design, the monotonic reading cannot is serialised, so round-trip marshalling and unmarshaling a time loses any Monoton IC information. T1 contains a monotonic reading, while T2 does not. Both the equality operator and reflect. Deepequal report, T1 and T2 is different while the Equal method properly reports, that these, the same. If you read the documentation for time, you'll see that it actually encourages the use of the Equal method instead of th e equality operator. The reason why the equality operator gets this wrong was that it compares the underlying unexported fields of time without Taking into account that the same time instance can has multiple representations.

Generally, in Go code, should is careful about whether types is comparable and if they is not, you should either use A custom definition of equality like the Equal method or convert the value to a canonical form which is stable.

Relying on Go runtime details

The final category of erroneous assumptions is relying on the internals of the Go runtime. Examples include:

• The ordering of when Goroutines is scheduled. This can is problematic when the ordering in which values appear in a channel changes as they is produced by several Goro Utines
• Assuming iterations over a map producing a deterministic ordering. Now, maps provide a random iteration order
• Relying on the exact timing of functions and the exact text output of panic messages or stack traces

One important detail about the runtime to note was that unsafe was not forward compatible.

Write forward compatible Go code

• Read the documentation carefully!
• Be careful of the hardcode
• Use the right comparison
• Use the race detector
• Be willing to update unsafe code

Breakages due to the toolchain

The second cause of forward incompatible Go code is because the toolchain changed some behavior this it promised to has. In order to explain how we uphold the promise, the Go team follows a rigorous test and release process.

Go Development Cycle

The development of the Go Toolchain is a 6-month process where the first 3 months be spent developing new features, Optim Ising performance, refactoring code, and generally making higher risk changes. The later 3 months is spent in a development freeze, where we focus on fixing bugs, improving documentation, and Generall Y stabilising the toolchain.

Throughout the entire development cycle, rigorous testing is performed. Every few days, a cut of the toolchain are used to build, run, and test an enormous suite consisting of over a million targ ETS of Google ' s production code. The chart above shows the number of regression failures discovered on this test suite over the 1.8 cycle.

The number of regression failures is proportional to the number of feature changes submitted. It is interesting to note that the climax of bugs occurs on October 31st, the day of the freeze.

Try out the go1.9beta!

Testing the Go1.9beta is an excellent-on-the-contribute to the community, help discover regression bugs that affect your C Odebase, and shepherd your own codebase to is ready to adopt the new release. You ' ll also is helping make Go a reliable language platform and contribute to the release occur on time. You can test by

• Go get golang.org/x/build/version/go1.9beta2 go1.9beta2 download
• Use the GO1.9BETA2 command as if it were the normal go command