>_
GolangStepByStep
Software Engineer

Versioning & Compatibility

Modules, semantic versioning, import versioning, deprecations

# The Lego Factory Analogy

Building software without versioning is like a Lego factory that constantly changes the size of its pegs without telling anyone. A customer buys a new white door piece, tries to snap it onto an old red wall piece, and their entire model breaks.

Module Versioning acts as an iron-clad contract between the factory (Library Authors) and the builders (You/Your App).

Go requires you to explicitly state: "My project requires the 2023 edition curve brackets perfectly mapped out." No matter what the factory does tomorrow, your application is mathematically locked to those secure brackets.

# Level 1: Dependencies and go.mod (Beginner)

In Go, external libraries are called Modules. The blueprint tracking these libraries is called go.mod.

module github.com/myname/my-app  // The name of your app

go 1.22  // The Go compiler version required

// The exact libraries and versions we need to compile!
require (
    github.com/gin-gonic/gin v1.9.1
    github.com/google/uuid v1.6.0
)

Running go mod tidy will look at your .go files, automatically discover any import statements, download the libraries, and lock them securely into your go.mod.

Along with it comes go.sum. It generates a cryptographic fingerprint (SHA-256 hash) of the downloaded library. If a bad actor modifies the external code secretly, the checksum fails and Go brutally stops the build to protect your server.

# Level 2: Semantic Versioning (Intermediate)

Go completely enforces Semantic Versioning (SemVer). Versions look like v1.4.2 (vMajor.Minor.Patch).

  • Patch (v1.4.2 to v1.4.3): A bug was fixed. It's completely safe to upgrade. Nothing functional changes.
  • Minor (v1.4.2 to v1.5.0): New features were added cleanly. It's completely safe. Old code will 100% still compile.
  • Major (v1.5.0 to v2.0.0): Warning: Code was permanently modified or deleted. Backward compatibility is intentionally broken.

The Golden Standard: Below v1.0.0 (like v0.9.3), you can break whatever you want natively. But the second you publish v1.0.0, you have formed a holy pact with your users not to break their compiled code unless you launch a distinct v2.

# Level 3: The Import Compatibility Rule for v2 (Advanced)

If a major version breaks all existing code, migrating an enterprise app from v1 to v2 is statistically terrifying.

Go solves this massively complex software engineering problem with the Import Compatibility Rule: New major versions must be fundamentally different packages in the actual import path.

import (
    // We import the standard original v1 router for legacy files
    "github.com/my-org/router"
    
    // We visually import v2 alongside it for brand new logic!
    routerV2 "github.com/my-org/router/v2" 
)

func main() {
    // Old logic hums along perfectly untouched
    router.StartLegacy()
    
    // New logic leverages the modern systems!
    routerV2.StartModern()
}

This completely eliminates "Upgrade Paralysis". You don't have to upgrade all 500 router files over a weekend. You can migrate them one file at a time over a whole year because Go treats v1 and v2 as structurally different dependencies entirely!

# Level 4: Graceful Deprecations (Expert)

If you realize your function ConnectAWS() is terribly designed, you cannot delete it in a v1.x update, because that would break SemVer.

Instead, experts use Deprecation Directives. You leave the broken function alive, but you explicitly label it as obsolete using standard tooling.

// Deprecated: ConnectAWS is insecure and has major memory leaks. 
// Please migrate to ConnectAWSV2 as soon as possible.
func ConnectAWS() {
    // ... we proxy to a safe function if possible, or just leave it
}

// ConnectAWSV2 provides secure architecture.
func ConnectAWSV2() {
    // ... perfect internal logic ...
}

Go tools, VS Code, and IDEs automatically parse the // Deprecated: tag and place a visible strikethrough over ConnectAWS() in every developer's screen who uses it.

The program still compiles successfully, but the user receives intense visual signals to migrate safely before you launch v2.0.0 and literally delete it.

practice & review