validations:
      required: false

  - type: textarea
    id: go-backwards-compatiblity
    attributes:
      label: Is this change backward compatible?
      description: Breaking the Go 1 compatibility guarantee is a large cost and requires a large benefit.
      placeholder: |
       Yes or No

       If yes, 

4. Using dist, build Go 1.x cmd/go (as go_bootstrap) with Go 1.x compiler toolchain.
5. Using go_bootstrap, build the remaining Go 1.x standard library and commands.

Because of backward compatibility, although the steps above say Go 1.20.6,
in practice any release ≥ Go 1.20.6 but < Go 1.x will work as the bootstrap base.
Releases ≥ Go 1.x are very likely to work as well.

internal symbols in the standard library (including the runtime) that
are not marked with `//go:linkname` on their definitions.
Similarly, the linker disallows references to such symbols from assembly
code.
For backward compatibility, existing usages of `//go:linkname` found in
a large open-source code corpus remain supported.
Any new references to standard library internal symbols will be disallowed.

---
title: "Go, Backwards Compatibility, and GODEBUG"
layout: article
---

<!--
This document is kept in the Go repo, not x/website,
because it documents the full list of known GODEBUG settings,
which are tied to a specific release.
-->

## Introduction {#intro}

Go's emphasis on backwards compatibility is one of its key strengths.
There are, however, times when we cannot maintain complete compatibility.

go1.txt (and similarly named files) are frozen once a version has been
shipped. Each file adds new lines but does not remove any.

except.txt lists features that may disappear without breaking true
compatibility.

Starting with go1.19.txt, each API feature line must end in "#nnnnn"
giving the GitHub issue number of the proposal issue that accepted
the new API. This helps with our end-of-cycle audit of new APIs.

		}
		return false
	}

	// Only check comparability if we don't have a more specific error.
	checkComparability := func() bool {
		if !Ti.IsComparable() {
			return true
		}
		// If T is comparable, V must be comparable.
		// If V is strictly comparable, we're done.
		if comparable(V, false /* strict comparability */, nil, nil) {
			return true
		}

		// the module to continue to build in GOPATH mode, and GOPATH-mode users
		// won't know about replacement aliasing. How important is it to maintain
		// compatibility?
		fmt.Fprintf(os.Stderr, "warning: %s imported as both %s and %s; making two copies.\n", realPath, realPath, pkg)
	}

	copiedFiles := make(map[string]bool)
	dst := filepath.Join(vdir, pkg)

// supports vendoring per https://golang.org/s/go15vendor.
// Use go/importer to obtain an ImporterFrom implementation.
type ImporterFrom interface {
	// Importer is present for backward-compatibility. Calling
	// Import(path) is the same as calling ImportFrom(path, "", 0);
	// i.e., locally vendored packages may not be found.
	// The types package does not call Import if an ImporterFrom
	// is present.
	Importer

				// Starting at GoStrictVersion, we no longer maintain compatibility with
				// versions older than what is listed in the go.mod file.
				compatVersion = goVersion
			}
		}
		if gover.Compare(compatVersion, goVersion) > 0 {
			// Each version of the Go toolchain knows how to interpret go.mod and
			// go.sum files produced by all previous versions, so a compatibility
			// version higher than the go.mod version adds nothing.

	library. To get the dependency without importing any specific
	symbols, use _ for local and remote.

	Example:
	//go:cgo_import_dynamic _ _ "libc.so.6"

	For compatibility with current versions of SWIG,
	#pragma dynimport is an alias for //go:cgo_import_dynamic.

//go:cgo_dynamic_linker "<path>"

	In internal linking mode, use "<path>" as the dynamic linker