# How the supportedGuidelines Function Filters Guidelines by Go Version

> Learn how supportedGuidelines filters Go guidelines by version using goversion.Compare, keeping only those matching your target Go version.

- Repository: [JetBrains/go-modern-guidelines](https://github.com/jetbrains/go-modern-guidelines)
- Tags: internals
- Published: 2026-09-04

---

**The `supportedGuidelines` function filters guidelines by comparing the target Go version against each guideline's `sinceVersion` field using `goversion.Compare`, retaining only guidelines where `sinceVersion` is less than or equal to the target version.**

The `JetBrains/go-modern-guidelines` repository provides a CLI tool to discover modern Go language features available in specific versions. At its core, the `supportedGuidelines` function in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) implements the version-based filtering logic that determines which recommendations are applicable to your codebase.

## How Version Filtering Works

The filtering process involves three distinct stages: loading the guideline data, resolving the target Go version, and performing semantic version comparisons.

### Loading Guidelines from Embedded JSON

At program initialization, the repository parses an embedded JSON file ([`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json)) into a slice of `modernGoGuideline` structs stored in the `modernGoGuidelines` variable. Each struct contains metadata including a `sinceVersion` field indicating when the feature became available.

### Resolving and Comparing Go Versions

Before filtering begins, the CLI resolves the target version string. The `internal/goversion` package handles this through two key functions:

- **`Resolve`** – Determines the version from CLI flags (`--go-version`), environment variables, or the local toolchain (lines 18-27 in [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go)).
- **`Compare`** – Parses version strings into major/minor integers and returns a signed integer indicating relative ordering (lines 37-48 in [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go)).

As implemented in [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go), the `Compare` function returns a value greater than zero if the first version is newer than the second, less than zero if older, and zero if equal.

### The supportedGuidelines Implementation

The `supportedGuidelines` function iterates over the loaded guidelines and applies the version constraint. Located at lines 61-68 in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go), the implementation uses `goversion.Compare` to check if the target version is greater than or equal to the guideline's `sinceVersion`:

```go
func supportedGuidelines(targetGoVersion string) []modernGoGuideline {
    var guidelines []modernGoGuideline
    for _, guideline := range modernGoGuidelines {
        if goversion.Compare(targetGoVersion, guideline.sinceVersion) >= 0 {
            guidelines = append(guidelines, guideline)
        }
    }
    return guidelines
}

```

The logic `goversion.Compare(targetGoVersion, guideline.sinceVersion) >= 0` effectively means: "Keep this guideline if it was introduced in the target version or earlier."

## Practical Usage Examples

While `supportedGuidelines` is an internal helper, higher-level functions like `ListText` expose this filtering capability to users programmatically and via the CLI.

### Command Line Interface

The CLI entry point in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) wires version resolution to the filtering logic. To see guidelines for a specific version:

```bash
go-modern-guidelines list --go-version=1.25

```

This command prints all guidelines valid for Go 1.25 and earlier, excluding features introduced in Go 1.26+.

### Programmatic Access

You can invoke the exported helpers from Go code to retrieve filtered results:

```go
package main

import (
    "fmt"
    "github.com/JetBrains/go-modern-guidelines/internal/guidelines"
)

func main() {
    // List guidelines supported by Go 1.27
    output := guidelines.ListText("1.27")
    fmt.Println(output)
}

```

The `ListText` function internally calls `supportedGuidelines` and formats the results into human-readable text, displaying only guidelines where the JSON `"since_version"` field is less than or equal to `1.27`.

## Summary

- **Data Source**: Guidelines load from [`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json) into `modernGoGuideline` structs at startup.
- **Version Resolution**: The `internal/goversion` package parses and compares semantic versions via `Resolve` and `Compare`.
- **Filter Logic**: `supportedGuidelines` in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) (lines 61-68) retains guidelines where `sinceVersion` ≤ target version using `goversion.Compare(target, since) >= 0`.
- **Public API**: `ListText` provides the primary interface for accessing filtered guidelines programmatically or via CLI.

## Frequently Asked Questions

### How does supportedGuidelines handle invalid version strings?

The `goversion.Compare` function in [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go) parses version strings into numeric major and minor components. While the function expects valid semantic versions (e.g., "1.22", "1.23.4"), the comparison logic focuses on the numeric values to ensure accurate filtering regardless of patch levels.

### Can I use supportedGuidelines directly in my own code?

No, `supportedGuidelines` is unexported (lowercase) and intended for internal use within the `internal/guidelines` package. Use the exported function `ListText` to retrieve filtered guidelines, or import the `internal/goversion` package directly if you only need version comparison logic for your own filtering.

### What happens if I don't specify a Go version in the CLI?

According to the source code in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go) and [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go), the tool resolves the version from the local Go toolchain when no `--go-version` flag is provided. This ensures you see guidelines compatible with your current development environment by default.

### Where are the guideline definitions stored?

Guideline definitions reside in [`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json) and are embedded into the binary at build time. Each entry includes fields like `id`, `description`, and `since_version`, which `supportedGuidelines` uses to determine applicability against your target Go version.