How to Add a New Guideline to guidelines.json and Regenerate Documentation in Go Modern Guidelines

Add a new guideline by creating a JSON object following the schema in internal/guidelines/schema/schema.go, inserting it into internal/guidelines/guidelines.json, validating with go test ./..., and regenerating FEATURES.md using go generate ./... or the generator at internal/guidelines/featuresgen/main.go.

The JetBrains/go-modern-guidelines repository manages Go best practices through a centralized JSON data store. Every rule lives in internal/guidelines/guidelines.json and human-readable documentation is automatically generated via a custom Go program. Understanding this pipeline allows contributors to extend the guideline set while keeping documentation synchronized.

Understanding the guidelines.json Schema

Before adding content, review the schema definition in internal/guidelines/schema/schema.go. The structure enforces type safety and consistency across all entries.

Required Fields

Every guideline object must include these fields:

• id – Stable identifier using lowercase and underscores (e.g., go_mod_tidy)
• since_version – First Go version where the rule applies (e.g., 1.22)
• modernizer – Boolean indicating if the go-modernizer tool can auto-apply the fix
• category – One of the predefined groupings (e.g., Collections, Strings, Modules)
• impact – Severity level: Low, Medium, High, or Critical
• guideline – Concise one-sentence description of the rule
• details – Extended explanation of the rationale and implementation
• examples – Array of objects containing before and after code snippets

Adding a New Guideline Step-by-Step

1. Define the Guideline Object

Create a JSON object adhering to the schema. Include meaningful before and after examples to demonstrate the transformation or recommendation.

{
  "id": "go_mod_tidy",
  "since_version": "1.22",
  "modernizer": true,
  "category": "Modules",
  "impact": "Low",
  "guideline": "Run `go mod tidy` as part of CI to keep `go.mod` and `go.sum` clean.",
  "details": "`go mod tidy` removes unused dependencies and adds missing ones. Enforcing it in CI prevents repository drift and ensures reproducible builds.",
  "examples": [
    {
      "before": [
        "// No explicit command in the build pipeline."
      ],
      "after": [
        "// CI step:",
        "//   go mod tidy && git diff --exit-code go.mod go.sum"
      ]
    }
  ]
}

2. Insert into guidelines.json

Locate internal/guidelines/guidelines.json and append your object to the top-level array. The order is not significant, but maintain valid JSON syntax with trailing commas after each object except the final one.

3. Validate Against the Schema

Run the repository's validation test to catch schema violations before regeneration:

go test ./...

The test in internal/guidelines/guidelines_test.go loads guidelines.json against the schema defined in schema.go. Failures provide immediate feedback on missing required fields or type mismatches.

4. Regenerate FEATURES.md

The repository uses a go:generate directive in internal/guidelines/guidelines.go:

//go:generate go run ./featuresgen guidelines.json ../../FEATURES.md

Execute the generator using either method:

# Run all go:generate directives in the module

go generate ./...

Or invoke the generator directly:

cd internal/guidelines
go run ./featuresgen guidelines.json ../../FEATURES.md

This command reads the updated JSON and rewrites FEATURES.md with a formatted markdown table containing all guidelines.

5. Commit Changes

Stage both the modified guidelines.json and the regenerated FEATURES.md to ensure the repository remains synchronized:

git add internal/guidelines/guidelines.json FEATURES.md
git commit -m "Add guideline: go_mod_tidy"

Key Files in the Generation Pipeline

Understanding these source files provides context for debugging or extending the workflow:

• internal/guidelines/guidelines.json – Central data store containing the entire rule set as a JSON array
• internal/guidelines/schema/schema.go – Defines the Go structs that enforce JSON schema validation
• internal/guidelines/featuresgen/main.go – The generator program that transforms JSON into markdown documentation
• internal/guidelines/guidelines.go – Contains the go:generate directive linking the generator to the build process
• internal/guidelines/guidelines_test.go – Unit tests ensuring JSON conformity to the schema

Summary

• Schema definition resides in internal/guidelines/schema/schema.go and mandates eight required fields including id, modernizer, and examples
• Data storage occurs in internal/guidelines/guidelines.json as a top-level JSON array
• Validation happens via go test ./... which executes guidelines_test.go
• Documentation generation uses go generate ./... or direct execution of internal/guidelines/featuresgen/main.go
• Output is written to FEATURES.md in the repository root
• Synchronization requires committing both the JSON source and regenerated markdown file

Frequently Asked Questions

What is the structure of guidelines.json?

The file contains a JSON array where each element is an object with required fields: id, since_version, modernizer, category, impact, guideline, details, and examples. The schema is defined in internal/guidelines/schema/schema.go and enforced by tests.

How do I validate my new guideline before committing?

Run go test ./... from the repository root. The test suite loads guidelines.json against the schema and reports any missing fields, type errors, or malformed JSON before you commit anything.

Can I run the documentation generator manually?

Yes. While go generate ./... is the standard approach, you can manually execute go run ./featuresgen guidelines.json ../../FEATURES.md from within the internal/guidelines directory. This is useful when debugging generator behavior or regenerating documentation outside the normal build flow.

Where is the generated documentation saved?

The generator writes to FEATURES.md in the repository root (relative path ../../FEATURES.md from the generator's location). This markdown file contains a formatted table of all guidelines and serves as the human-readable reference for the project.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}