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

> Learn how to add a new guideline to guidelines.json and regenerate documentation in Go Modern Guidelines. Follow our simple steps to update your project's guidelines.

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

---

**Add a new guideline by creating a JSON object following the schema in [`internal/guidelines/schema/schema.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/schema/schema.go), inserting it into [`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json), validating with `go test ./...`, and regenerating [`FEATURES.md`](https://github.com/JetBrains/go-modern-guidelines/blob/main/FEATURES.md) using `go generate ./...` or the generator at [`internal/guidelines/featuresgen/main.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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.

```json
{
  "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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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:

```bash
go test ./...

```

The test in [`internal/guidelines/guidelines_test.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines_test.go) loads [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) against the schema defined in [`schema.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go):

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

```

Execute the generator using either method:

```bash

# Run all go:generate directives in the module

go generate ./...

```

Or invoke the generator directly:

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

```

This command reads the updated JSON and rewrites [`FEATURES.md`](https://github.com/JetBrains/go-modern-guidelines/blob/main/FEATURES.md) with a formatted markdown table containing all guidelines.

### 5. Commit Changes

Stage both the modified [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) and the regenerated [`FEATURES.md`](https://github.com/JetBrains/go-modern-guidelines/blob/main/FEATURES.md) to ensure the repository remains synchronized:

```bash
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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json)** – Central data store containing the entire rule set as a JSON array
- **[`internal/guidelines/schema/schema.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/schema/schema.go)** – Defines the Go structs that enforce JSON schema validation
- **[`internal/guidelines/featuresgen/main.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/featuresgen/main.go)** – The generator program that transforms JSON into markdown documentation
- **[`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go)** – Contains the `go:generate` directive linking the generator to the build process
- **[`internal/guidelines/guidelines_test.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines_test.go)** – Unit tests ensuring JSON conformity to the schema

## Summary

- **Schema definition** resides in [`internal/guidelines/schema/schema.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/schema/schema.go) and mandates eight required fields including `id`, `modernizer`, and `examples`
- **Data storage** occurs in [`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json) as a top-level JSON array
- **Validation** happens via `go test ./...` which executes [`guidelines_test.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines_test.go)
- **Documentation generation** uses `go generate ./...` or direct execution of [`internal/guidelines/featuresgen/main.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/featuresgen/main.go)
- **Output** is written to [`FEATURES.md`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/FEATURES.md) in the repository root (relative path [`../../FEATURES.md`](https://github.com/JetBrains/go-modern-guidelines/blob/main/../../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.