Support golangci-lint v2 for Go lint (tools)

[deltics]

When reviewing a Go project that contains a golangci-lint v2 configuration file, a warning is produced in the review stating that this is not supported and that the review has not benefited from any lint reports.

The documentation for the golangci-lint tool does not mention the supported 1.x version and incorrectly links to v2+ configuration documentation on the tool documentation site.

The documentation should identify the supported version and provide options for working with the v2 linter. e.g. providing an additional v1 configuration file specifically for CodeRabbit use and how to configure that alongside a v2 configuration file for use in CI/CD pipelines.

[linear]

ENG-1707 Support golangci-lint v2 for Go lint (tools)

[traycerai]

Plan

Observations

After analyzing the current documentation structure and researching external sources, I found that the golangci-lint documentation lacks any version compatibility information and links to the latest (v2+) configuration docs. CodeRabbit currently supports only golangci-lint v1.x, which causes warnings when v2 configurations are detected. The documentation needs clear version guidance and practical solutions for dual-configuration setups.

The main documentation file has a clean structure with logical insertion points for new content, and only two other files reference golangci-lint across the entire documentation. This makes the update scope manageable while ensuring comprehensive coverage of the version compatibility issue.

Approach

The task requires updating CodeRabbit's documentation to clarify that only golangci-lint v1.x is supported, while providing guidance for users with v2 configurations. The primary issue is that the current documentation doesn't specify version compatibility and incorrectly links to v2+ configuration documentation, causing confusion when users receive warnings about unsupported v2 configs.

The solution involves updating the main golangci-lint documentation page with version-specific information, correcting external links to point to v1 documentation, and adding practical guidance for teams using v2 in CI while maintaining v1 compatibility for CodeRabbit. A minor update to the tools list will also add a version footnote for immediate clarity.

Reasoning

I analyzed the current golangci-lint documentation to understand its structure and identify missing version information. I searched across all documentation files to find references to golangci-lint that might need updates. I researched external sources to confirm CodeRabbit's actual golangci-lint version support (v1 only), located authoritative v1 documentation URLs, and identified the specific warning messages users encounter with v2 configurations. This comprehensive analysis revealed the exact changes needed to resolve the GitHub ticket.

Proposed File Changes

📄 docs/tools/golangci-lint.md ^(MODIFY) 🔗

Update the golangci-lint documentation to include comprehensive version compatibility information and practical guidance for v2 users.

Add Version Compatibility Section (after line 31, before Links section):
Insert a new ## Version Compatibility section that clearly states CodeRabbit currently supports golangci-lint v1.x only. Explain that v2 configuration files are not recognized and will cause CodeRabbit to fall back to internal defaults, resulting in no lint issues being reported in reviews. Include the specific warning message users will see: "Error: can't load config: typecheck is not a linter, it cannot be enabled or disabled".

Add Dual Configuration Guidance Section:
Insert a new ## Using v2 in CI while CodeRabbit uses v1 section after the version compatibility section. Provide a practical example showing how to maintain separate configuration files:

• .golangci.yaml for v2 (used in CI/CD)
• .golangci_v1.yaml for v1 (used by CodeRabbit)
• Example .coderabbit.yaml configuration setting reviews.tools.golangci-lint.config_file: ".golangci_v1.yaml"

Mention the golangci-lint migrate command for converting between versions and provide tips for keeping rule sets aligned between the two configurations.

Update External Link (line 34):
Replace the current link [golangci-lint Configuration](https://golangci-lint.run/usage/configuration/) with a v1-specific link: [golangci-lint v1 Configuration](https://github.com/golangci/golangci-lint/blob/v1.54.2/.golangci.example.yml). Add a brief explanation that this links to v1 documentation since CodeRabbit doesn't support v2 configuration format.

Add Migration Tool Reference:
In the Links section, add a reference to the official migration guide: [golangci-lint Migration Guide](https://golangci-lint.run/product/migration-guide/#command-migrate) for users who need to convert between v1 and v2 formats.

Ensure all new content follows the existing documentation style and maintains the current heading hierarchy. The updated structure should flow logically from basic configuration to version-specific guidance to external resources.

📄 docs/tools/list.md ^(MODIFY) 🔗

References

• 📄 docs/tools/golangci-lint.md ^(MODIFY)

Add a version-specific footnote to the golangci-lint entry in the tools list to provide immediate clarity about version limitations.

Update Table Entry (line 24):
Modify the golangci-lint table entry from Go | [golangci-lint][golangci-lint] | Code Quality to Go | [golangci-lint][golangci-lint]* | Code Quality by adding an asterisk to indicate a footnote.

Add Footnote:
At the bottom of the tools table, add a footnote: * golangci-lint v1.x only to clarify the version limitation. This ensures users understand the version restriction before navigating to the detailed tool documentation.

The internal markdown reference link on line 63 [golangci-lint]: /tools/golangci-lint.md should remain unchanged as it correctly points to the main tool documentation that will contain the detailed version information.

Diagram

sequenceDiagram
    participant User as Developer
    participant CR as CodeRabbit
    participant Docs as Documentation
    participant Config as Config Files
    
    User->>Docs: Reads golangci-lint documentation
    Docs->>User: Shows version compatibility (v1 only)
    Docs->>User: Provides dual-config guidance
    
    User->>Config: Creates .golangci.yaml (v2 for CI)
    User->>Config: Creates .golangci_v1.yaml (v1 for CodeRabbit)
    User->>Config: Updates .coderabbit.yaml with config_file setting
    
    CR->>Config: Reads specified v1 config file
    CR->>User: Provides lint feedback in review
    
    Note over User,CR: No more warnings about unsupported v2 config
    Note over Config: Both CI and CodeRabbit work with appropriate versions

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end. Make sure you fix all the linting, compilation or validation issues after successful implementation of the plan.

### Observations

After analyzing the current documentation structure and researching external sources, I found that the golangci-lint documentation lacks any version compatibility information and links to the latest (v2+) configuration docs. CodeRabbit currently supports only golangci-lint v1.x, which causes warnings when v2 configurations are detected. The documentation needs clear version guidance and practical solutions for dual-configuration setups.

The main documentation file has a clean structure with logical insertion points for new content, and only two other files reference golangci-lint across the entire documentation. This makes the update scope manageable while ensuring comprehensive coverage of the version compatibility issue.

### Approach

The task requires updating CodeRabbit's documentation to clarify that only golangci-lint v1.x is supported, while providing guidance for users with v2 configurations. The primary issue is that the current documentation doesn't specify version compatibility and incorrectly links to v2+ configuration documentation, causing confusion when users receive warnings about unsupported v2 configs.

The solution involves updating the main golangci-lint documentation page with version-specific information, correcting external links to point to v1 documentation, and adding practical guidance for teams using v2 in CI while maintaining v1 compatibility for CodeRabbit. A minor update to the tools list will also add a version footnote for immediate clarity.

### Reasoning

I analyzed the current golangci-lint documentation to understand its structure and identify missing version information. I searched across all documentation files to find references to golangci-lint that might need updates. I researched external sources to confirm CodeRabbit's actual golangci-lint version support (v1 only), located authoritative v1 documentation URLs, and identified the specific warning messages users encounter with v2 configurations. This comprehensive analysis revealed the exact changes needed to resolve the GitHub ticket.

## Mermaid Diagram

sequenceDiagram
    participant User as Developer
    participant CR as CodeRabbit
    participant Docs as Documentation
    participant Config as Config Files
    
    User->>Docs: Reads golangci-lint documentation
    Docs->>User: Shows version compatibility (v1 only)
    Docs->>User: Provides dual-config guidance
    
    User->>Config: Creates .golangci.yaml (v2 for CI)
    User->>Config: Creates .golangci_v1.yaml (v1 for CodeRabbit)
    User->>Config: Updates .coderabbit.yaml with config_file setting
    
    CR->>Config: Reads specified v1 config file
    CR->>User: Provides lint feedback in review
    
    Note over User,CR: No more warnings about unsupported v2 config
    Note over Config: Both CI and CodeRabbit work with appropriate versions

## Proposed File Changes

### docs/tools/golangci-lint.md(MODIFY)

Update the golangci-lint documentation to include comprehensive version compatibility information and practical guidance for v2 users.

**Add Version Compatibility Section (after line 31, before Links section):**
Insert a new `## Version Compatibility` section that clearly states CodeRabbit currently supports golangci-lint v1.x only. Explain that v2 configuration files are not recognized and will cause CodeRabbit to fall back to internal defaults, resulting in no lint issues being reported in reviews. Include the specific warning message users will see: "Error: can't load config: typecheck is not a linter, it cannot be enabled or disabled".

**Add Dual Configuration Guidance Section:**
Insert a new `## Using v2 in CI while CodeRabbit uses v1` section after the version compatibility section. Provide a practical example showing how to maintain separate configuration files:
- `.golangci.yaml` for v2 (used in CI/CD)
- `.golangci_v1.yaml` for v1 (used by CodeRabbit)
- Example `.coderabbit.yaml` configuration setting `reviews.tools.golangci-lint.config_file: ".golangci_v1.yaml"`

Mention the `golangci-lint migrate` command for converting between versions and provide tips for keeping rule sets aligned between the two configurations.

**Update External Link (line 34):**
Replace the current link `[golangci-lint Configuration](https://golangci-lint.run/usage/configuration/)` with a v1-specific link: `[golangci-lint v1 Configuration](https://github.com/golangci/golangci-lint/blob/v1.54.2/.golangci.example.yml)`. Add a brief explanation that this links to v1 documentation since CodeRabbit doesn't support v2 configuration format.

**Add Migration Tool Reference:**
In the Links section, add a reference to the official migration guide: `[golangci-lint Migration Guide](https://golangci-lint.run/product/migration-guide/#command-migrate)` for users who need to convert between v1 and v2 formats.

Ensure all new content follows the existing documentation style and maintains the current heading hierarchy. The updated structure should flow logically from basic configuration to version-specific guidance to external resources.

### docs/tools/list.md(MODIFY)

References: 

- docs/tools/golangci-lint.md(MODIFY)

Add a version-specific footnote to the golangci-lint entry in the tools list to provide immediate clarity about version limitations.

**Update Table Entry (line 24):**
Modify the golangci-lint table entry from `Go | [golangci-lint][golangci-lint] | Code Quality` to `Go | [golangci-lint][golangci-lint]* | Code Quality` by adding an asterisk to indicate a footnote.

**Add Footnote:**
At the bottom of the tools table, add a footnote: `* golangci-lint v1.x only` to clarify the version limitation. This ensures users understand the version restriction before navigating to the detailed tool documentation.

The internal markdown reference link on line 63 `[golangci-lint]: /tools/golangci-lint.md` should remain unchanged as it correctly points to the main tool documentation that will contain the detailed version information.

---

Developer Humor

Why did the golangci-lint config file break up with CodeRabbit?
Because it was too v2-advanced for their v1-derful relationship! 💔
But don't worry - with dual configs, they can still be friends...
One for CI, one for reviews - a perfect arrangement! 🤝
┌─────────────────┐
│ .golangci.yaml │ ← v2 (CI)
│ .golangci_v1.yaml│ ← v1 (CodeRabbit)
└─────────────────┘

---

Execution Information

Branch: main
Commit: da9081a

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.