[go-fan] Go Module Review: golang.org/x/tools/gopls

[github-actions[bot]]

🐹 Go Fan — gopls Review

Today's module is golang.org/x/tools/gopls — the official Go language server. This module was selected because it had the most recent commit activity (golang/tools was last pushed 2026-02-19, the most recently updated direct dependency).

---

Module Overview

gopls is Go's official Language Server Protocol (LSP) implementation, maintained by the Go team. It provides IDE features: code completion, go-to-definition, find-references, hover documentation, formatting, and diagnostics.

• Version in go.mod: v0.21.1 (latest release — ✅ up to date)
• License: BSD-3-Clause
• Latest release: gopls/v0.21.1 (2026-02-12) — bugfix for golang/go#77260, references broken when highlighting function names

---

Current Usage in gh-aw

gopls plays two distinct roles in this repository:

Role 1: Developer Tool (Version Pinning)

• Files: tools.go:12, Makefile:400
• Import count: 1 blank import (_ "golang.org/x/tools/gopls")
• Pattern: Standard Go tools pattern with //go:build tools build tag
• Install: go install golang.org/x/tools/gopls@v0.21.1 via make tools

This is the canonical Go pattern for version-pinning development tools. All contributors install the exact same gopls version, ensuring consistent LSP behavior across environments.

Role 2: Serena Workflow Configuration Schema

• Files: pkg/workflow/tools_types.go:310, pkg/workflow/tools_parser.go:404-405
• Field: GoplsVersion string \yaml:"gopls-version,omitempty"`onSerenaLangConfig`
• Parser: parseSerenaTool() reads gopls-version from workflow frontmatter

Users can specify gopls-version in their workflow YAML:

tools:
  serena:
    languages:
      go:
        version: "1.21"
        gopls-version: "v0.14.2"

---

Research Findings

Recent Updates (v0.19–v0.21)

Version	Notable Changes
v0.21.1	Fix: references broken when highlighting function names
v0.21.0	Multiple improvements (see release notes)
v0.19.1	Reverted importsSource default back to goimports after bug #74280
v0.19.0	Added gopls check subcommand with -severity flag

Best Practices from Maintainers

• Use go install golang.org/x/tools/gopls@(version) (not go get) for tool installation
• The tools.go blank-import pattern is the recommended approach for version pinning
• Use gopls check ./... for CI-friendly diagnostics (no LSP session needed)
• GOFLAGS=-mod=mod gopls check for projects with unusual module configurations

---

Improvement Opportunities

🔴 Important Finding: gopls-version Field Is Parsed But Never Used

This is the most significant finding from this review.

The GoplsVersion field is parsed by parseSerenaTool() in tools_parser.go and stored in SerenaLangConfig, but it is never passed to any actual output. Here's why:

1. The original intent was to have GenerateSerenaLanguageServiceSteps() use it to install gopls on the host runner
2. Serena was later migrated to run inside a Docker container
3. GenerateSerenaLanguageServiceSteps() (runtime_step_generator.go:51) is now explicitly marked obsolete — it always returns an empty slice
4. The renderSerenaMCPConfigWithOptions() function that generates the actual Serena container config does not reference GoplsVersion at all

Impact: Users who configure gopls-version: in their workflow frontmatter get no benefit from it. The field is accepted without error, silently ignored.

Options:

• A: Pass GoplsVersion as an environment variable GOPLS_VERSION to the Serena container (if the Serena container supports selecting gopls versions)
• B: Deprecate the field in the schema and emit a warning when it is set
• C: Document explicitly that gopls-version is a no-op in Docker mode (current default)

🟡 Quick Win: Outdated gopls-version Examples in Docs and Test Workflows

Three files use gopls-version: "v0.14.2" — which is 7 minor versions behind the current v0.21.1:

File	Current Value	Suggested
docs/src/content/docs/guides/serena.md:75	"v0.14.2"	"latest"
pkg/cli/workflows/test-serena-go-config.md:12	"v0.14.2"	"latest"
pkg/cli/workflows/test-serena-long.md:14	"v0.14.2"	"latest"

Since the field is currently a no-op anyway, using "latest" would be more accurate as an example.

🟡 Feature: Use gopls check in CI

gopls check (available since v0.19.0) runs Go diagnostics without a full LSP session — it's suitable for CI pipelines. Could be added to make golint or as a new make gopls-check target:

gopls check ./...

This can catch issues that go vet misses, and since gopls is already installed via make tools, there's no additional dependency.

🔵 Dead Code: GenerateSerenaLanguageServiceSteps Call Sites

The function is called in two places in compiler_yaml_main_job.go (lines 139, 538) but always returns an empty slice. These call sites add noise and could be cleaned up when the function is eventually removed.

---

Recommendations

1. Decide the fate of gopls-version: Either wire it up to actually do something (e.g., pass to Serena container as env var), or deprecate it with a schema warning. The current state — silently parsed and ignored — is a subtle UX issue.

2. Update stale docs examples: Change gopls-version: "v0.14.2" → "latest" in 3 files. Low-effort, high-clarity improvement.

3. Consider adding gopls check to CI: Now that gopls is already pinned and installed, gopls check is a free diagnostic improvement available on every developer machine and CI run.

4. Track dead code: GenerateSerenaLanguageServiceSteps and its call sites are clearly obsolete. Track for cleanup in a future housekeeping PR.

---

Next Steps

• Resolve gopls-version field lifecycle (wire up, deprecate, or document as no-op)
• Update 3 documentation files from v0.14.2 → "latest"
• Evaluate adding gopls check ./... to linting targets
• Remove GenerateSerenaLanguageServiceSteps call sites when appropriate

---

References:

• §22215120324
• gopls releases
• gopls v0.21.0 release notes

Module summary saved to: scratchpad/mods/golang-x-tools-gopls.md
Generated by Go Fan — round-robin state saved to cache

AI generated by Go Fan

• expires on Feb 27, 2026, 7:27 AM UTC