# How the ListText Function Filters Guidelines by Target Go Version in JetBrains/go-modern-guidelines

> Discover how the ListText function in JetBrains go modern guidelines filters guidelines by target Go version using semantic version comparison.

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

---

**The `ListText` function filters embedded guidelines by comparing the target Go version against each guideline's `sinceVersion` field using semantic version comparison, returning only those applicable to the specified version.**

The JetBrains/go-modern-guidelines repository helps developers adopt modern Go idioms by providing version-aware recommendations. The `ListText` function serves as a primary interface for retrieving applicable guideline IDs and summaries based on a specific Go release, ensuring output contains only patterns supported by the target environment.

## How ListText Filters Guidelines by Go Version

The filtering pipeline operates through a three-stage process involving version comparison and text formatting.

### Entry Point and Delegation

In [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) at lines 63-66, the `ListText` function receives the target version as a string parameter. It immediately delegates to `supportedGuidelines` for filtering, then passes the resulting slice to `toGuidelinesText` for formatting.

### Semantic Version Comparison

The `supportedGuidelines` function performs the core filtering logic between lines 61-68. It iterates over the embedded `modernGoGuidelines` slice—data generated from the embedded [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) file—and evaluates each guideline's `sinceVersion` field against the target version using `goversion.Compare`. The condition `goversion.Compare(targetGoVersion, guideline.sinceVersion) >= 0` retains only guidelines introduced in the target version or earlier.

### Text Formatting and Output

After filtering, `toGuidelinesText` (lines 68-73 in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go)) transforms the slice into the final output format. It constructs strings in the pattern `"<id>: <summary>"` for each guideline and joins them with newline characters, producing the newline-separated list returned to the caller.

## Key Components Supporting the Filter

Several components work together to enable accurate version-based filtering:

- **modernGoGuidelines**: An embedded slice in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) (lines 28-33) containing all guideline definitions with their `sinceVersion` metadata, sourced from the embedded [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) file.

- **goversion.Compare**: Implemented in [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go), this function performs accurate semantic version comparison between the target version and each guideline's introduction version.

- **supportedGuidelines**: The helper function in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) (lines 61-68) that orchestrates the iteration and filtering logic.

## Usage Example

The following example demonstrates retrieving filtered guidelines for specific Go versions:

```go
package main

import (
	"fmt"

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

func main() {
	// List guidelines applicable to Go 1.20
	fmt.Println("Guidelines for Go 1.20:")
	fmt.Println(guidelines.ListText("1.20"))

	// List guidelines for the latest known version
	fmt.Println("\nGuidelines for the latest known version:")
	fmt.Println(guidelines.ListText(guidelines.LatestKnownVersion()))
}

```

**Output:**

```

Guidelines for Go 1.20:
G001: Prefer early returns
G002: Use `errors.Is` for error comparison
G005: Use fmt.Sprintf for string building
...

```

The output excludes any guideline introduced in a Go version newer than the target, ensuring compatibility with the requested release.

## Summary

- The `ListText` function relies on `supportedGuidelines` to filter the embedded `modernGoGuidelines` slice based on semantic version comparison.
- Version filtering uses `goversion.Compare` to check if `targetGoVersion >= guideline.sinceVersion`.
- Only guidelines with a `sinceVersion` less than or equal to the target are included in the output.
- The final text formatting joins guideline IDs and summaries with newlines via `toGuidelinesText`.

## Frequently Asked Questions

### How does ListText determine which guidelines are applicable?

`ListText` delegates to `supportedGuidelines`, which iterates through the embedded `modernGoGuidelines` slice and uses `goversion.Compare` to verify that the target version is greater than or equal to each guideline's `sinceVersion`. Only guidelines meeting this condition are retained.

### Where are the guideline definitions stored?

Guideline definitions reside in the embedded [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) file, which is compiled into the `modernGoGuidelines` slice in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go). This data structure contains every guideline ID, summary, and the Go version in which it was introduced.

### How does the version comparison handle different Go releases?

The comparison relies on `goversion.Compare` from [`internal/goversion/goversion.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/goversion/goversion.go), which implements semantic version comparison. This ensures accurate ordering between major, minor, and patch versions when determining guideline applicability.

### What format does the filtered output follow?

The `toGuidelinesText` helper formats each applicable guideline as `"<id>: <summary>"` and joins multiple entries with newline characters, producing a single string where each line represents one supported guideline for the target Go version.