golangci-lint 贡献工作流完全指南从环境搭建、PR 提交流程到版本发布【免费下载链接】golangci-lintFast linters runner for Go项目地址: https://gitcode.com/gh_mirrors/go/golangci-lint本指南面向希望向 golangci-lintFast linters runner for Go贡献代码、文档或新 linter 的开发者完整梳理项目官方的参与流程环境准备与自检、变更测试、文档参数更新、Discussion 先行、Pull Request 提交与 CI 检查以及新版本发布的版本策略与自动化流程。读完本文你将掌握一套从make build到打 tag 发布的可执行贡献路径并能理解其背后由 Makefile、GitHub Actions 工作流与配置生成脚本共同构成的工程化支撑。前置约定参与即代表认同行为准则在开始任何贡献之前请注意参与 golangci-lint 项目即表示你同意遵守项目的行为准则Code of Conduct。这一点在官方贡献工作流文档 docs/content/docs/contributing/workflow.md 的开篇即被明确声明。若你在贡献过程中遇到任何违反准则的行为应通过项目维护渠道反馈而不是自行处理。环境准备一台可以构建 golangci-lint 的机器golangci-lint 使用 Go 语言编写因此在本地开发前需要满足以下前置条件make项目几乎所有构建、测试、文档生成任务都由 Makefile 驱动Go需安装与仓库go.mod要求兼容的 Go 工具链版本。环境就绪后第一步是 fork 并 clone golangci-lint 仓库。建议使用以下方式验证本机环境是否一切正常make build ./golangci-lint run -vmake build会调用 Makefile 中的build目标执行go build -o golangci-lint ./cmd/golangci-lint见 Makefile在仓库根目录产出名为golangci-lint的二进制文件Windows 下为golangci-lint.exe见 Makefile./golangci-lint run -v使用刚构建出的二进制对当前仓库自身执行一次完整的 lint 检查并开启-v详细输出。这一步既是环境自检也是dogfooding——用项目自己检查自己。如果这两条命令都能顺利通过说明构建链与 Go 环境配置正确可以开始编码了。附带了解Makefile 提供的其他常用目标除了build根目录 Makefile 中还提供了与开发验证密切相关的目标贡献者在不同场景下会用到build_race以-race竞态检测模式构建用于排查并发问题test默认目标先构建再对仓库执行 lint 与全量单元测试详见下文测试你的变更test_race以竞态检测模式运行 lint 与测试test_integration/test_integration_fix针对test/testdata下指定文件的集成测试例如Toutput.go make test_integration。测试你的变更make test一站式验证当你对代码改动感到满意后官方工作流建议运行make test该命令runs all the linters and tests运行全部 linter 与测试。查看 Makefile 可以看到其具体行为test: export GOLANGCI_LINT_INSTALLED true test: CGO_ENABLED1 test: build GL_TEST_RUN1 ./$(BINARY) run -v GL_TEST_RUN1 go test -v -parallel 2 ./...即make test会依次完成以CGO_ENABLED1构建最新二进制用该二进制对仓库自身跑一遍完整 lintGL_TEST_RUN1 ./golangci-lint run -v保证新代码本身不引入 lint 问题运行全量 Go 单元测试go test -v -parallel 2 ./...覆盖pkg、internal、test等全部包。提示GL_TEST_RUN1环境变量用于标记正在被 golangci-lint 自身测试的运行场景在仓库测试代码中有对应的行为分支避免测试与自检相互干扰。集成测试覆盖了大量真实场景例如test/testdata下按 linter 组织的示例代码与期望输出以及 test/run_test.go、test/linters_test.go 等针对整体运行流程的测试。若你的改动影响某个具体 linter 的输出格式对应的*_integration_test.go分布在 pkg/golinters 各子目录中会是验证重点。更新文档参数写入.golangci.next.reference.yml如果你在贡献中新增或修改了配置参数例如为某个 linter 增加新的设置项必须同步更新仓库根目录下的 .golangci.next.reference.yml 文件。这份文件是下一版本的完整配置参考包含所有可用配置项及其默认值以注释形式标注例如# This file contains all available configuration options # with their default values (in comments). # # This file is not a configuration example, # it contains the exhaustive configuration with explanations of the options. # Defines the configuration version. # The only possible value is 2. version: 2 linters: # Default set of linters. # The value can be: # - standard: the Default linters # - all: enables all linters by default. # - none: disables all linters by default. # - fast: enables only linters considered as fast default: all从仓库现状看该文件超过 5000 行是文档站配置章节的数据来源之一。其命名中的next表明它面向下一个未发布版本新参数先在此登记待版本发布后才会固化到正式参考文件并展现在官方文档中。因此新增或变更参数是每个涉及配置的 PR 的必备环节遗漏将导致文档与实际行为不一致。创建 Discussion开 PR 之前的第一步golangci-lint 项目要求在打开 Pull Request 之前必须先创建 Discussion讨论帖。这是硬性前置流程尤其对于新 linter 的提议。项目为不同主题设置了讨论分类其中为新增 linter 专门设立了 New Linter Proposals 分类。仓库中对应提供了讨论模板 .github/DISCUSSION_TEMPLATE/new-linter-proposals.yml用于规范新 linter 提案的信息结构此外还有配套的检查清单 .github/new-linter-checklist.md帮助提案者与维护者逐项核对新增 linter 的完整性要求。如果你计划新增 linter建议同时阅读 docs/content/docs/contributing/new-linters.md了解添加一个 linter 所涉及的内部结构pkg/golinters下的实现、pkg/lint/lintersdb中的注册、测试与文档——这些都属于工作流的延伸准备能显著提高提案被接受的概率。提交 Pull Request基于main分支当维护者在 Discussion 中批准了你的提案尤其是 linter 提案后就可以进入提交阶段将你的功能分支推送到 fork 仓库在 golangci-lint 原仓库针对main分支打开 Pull Request。仓库提供了 PR 模板 .github/PULL_REQUEST_TEMPLATE.md提交前应参照模板填写变更说明、测试情况与相关讨论链接。PR 检查CLA 与 CI 自动化PR 打开后有两类检查需要关注CLA 签署首先需要接受 Contributor License Agreement贡献者许可协议。CLA assistant 会在 PR 上自动发表评论提示签署。未签署 CLA 的 PR 不会被合并。GitHub Actions CI 检查项目通过 GitHub Actions 运行多组 CI 检查工作流定义集中在 .github/workflows 目录与本流程直接相关的包括pr-checks.ymlPR 基础检查构建、生成产物一致性等pr-tests.yml运行测试套件pr-documentation.yml校验文档与配置参考的同步性new-linter-checklist.yml针对新 linter 的自动化清单校验codeql.yml代码安全静态分析。这意味着一个合规的 PR 不仅代码要正确还需要通过格式、lint、生成文件一致性、文档同步等多维度的机器检查。建议在本地完整执行make test后再提交尽量把问题挡在 CI 之前。新版本发布tag 触发 自动化流水线发布流程同样由工作流文档给出明确指引并与仓库内的版本策略、工作流脚本严格对应。版本策略理解何时升 minor / patch / major在发布之前请先阅读版本策略文档 docs/content/docs/product/roadmap.md原工作流文档以our versioning policy指代。其核心结论是 golangci-lint 遵循语义化版本SemVer但结合代码质量工具的特性做了细化约定Patch 版本预期不破坏你的 lint 构建单个 linter 的 patch 级更新导致报错减少、CLI 或核心包加载、runner、后处理器等的 bug 修复、文档改进、非面向用户的内部重构与测试调整、失败发布的重新发布Minor 版本可能因新发现的问题破坏 lint 构建linter 的 minor/major 更新导致报错增多、新增 linter、弃用某个配置项或 linter、新增 CLI 命令、配置的向后不兼容变更Major 版本大概率破坏 lint 构建影响面巨大的向后不兼容配置变更。基于该策略任何 minor 更新都可能比前一版本报告更多问题因此官方建议固定 minor 版本号、同时允许 patch 版本浮动以保证构建结果可控官方 GitHub Action 即采用此策略。创建 tag 触发发布发布操作本身非常简单创建形如vX.Y.Z的 tag新 minor 版本必须带上零 patch 号例如v1.99.0而不是v1.99——这与 scripts/gen_github_action_config/main.go 中的版本解析逻辑parseVersion同时支持 2 段与 3 段版本号但规范发布要求 3 段完整版本保持一致推送 tag 后GitHub Actions 的 release.yml 工作流会自动触发on: push: tags: [v*]使用 goreleaser 完成多平台构建、容器镜像发布、SBOM 与 attestation 生成等一系列发布动作最终产出 GitHub Release 并同步到各分发渠道。发布后更新 Action 配置Release 发布完成后还需要更新 GitHub Action 的版本映射配置。工作流文档给出了明确命令make assets/github-action-config.json该命令对应 Makefile 中的目标实际执行的是scripts/gen_github_action_config目录下的 Go 程序assets/github-action-config.json: FORCE $(BINARY) cd ./scripts/gen_github_action_config/; go run . ../../$从 scripts/gen_github_action_config/main.go 的源码可以看到该程序会通过 GitHub GraphQL API 拉取全部 release需要GITHUB_TOKEN环境变量见fetchAllReleases为每个 minor 版本计算对应的最大 patch 版本并生成版本 → 可下载资产 URL的映射buildConfig分别产出github-action-config.json、github-action-config-v1.json仅兼容 v1 系列最低支持 v1.28.3与github-action-config-v2.jsonv2 系列仓库 assets 目录中的三个 JSON 文件即该脚本的输出结果。这样golangci-lint-action就能根据用户指定的 minor 版本自动解析到最新的 patch 版本并下载对应二进制实现固定 minor、滚动 patch的版本策略落地。更多贡献主题的延伸阅读工作流文档之外docs/content/docs/contributing 目录还提供了与贡献流程配套的专题文档可作为深度参与的下一步architecture.mdgolangci-lint 的整体架构包加载、runner、后处理器、输出器如何协作new-linters.md新增 linter 的完整实现指南debug.md调试 golangci-lint 运行过程的方法faq.md贡献过程中的常见问题website.md参与文档站本身建设的规范。总结golangci-lint 的贡献工作流可以浓缩为一条清晰的链路搭建环境并自检 → 修改代码 →make test验证 → 同步.golangci.next.reference.yml→ 先 Discussion 后 PR → 通过 CLA 与 CI 检查 → 合并发布时则遵循 SemVer 细化策略打 tag由 release.yml 自动构建最后通过make assets/github-action-config.json更新 Action 版本映射。每个环节都有仓库内的 Makefile 目标、工作流文件或生成脚本作为可验证的支撑照此流程操作即可让贡献过程与项目维护者的预期完全对齐。【免费下载链接】golangci-lintFast linters runner for Go项目地址: https://gitcode.com/gh_mirrors/go/golangci-lint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 golangci-lint 贡献工作流完全指南：从环境搭建、PR 提交流程到版本发布
golangci-lint 贡献工作流完全指南从环境搭建、PR 提交流程到版本发布【免费下载链接】golangci-lintFast linters runner for Go项目地址: https://gitcode.com/gh_mirrors/go/golangci-lint本指南面向希望向 golangci-lintFast linters runner for Go贡献代码、文档或新 linter 的开发者完整梳理项目官方的参与流程环境准备与自检、变更测试、文档参数更新、Discussion 先行、Pull Request 提交与 CI 检查以及新版本发布的版本策略与自动化流程。读完本文你将掌握一套从make build到打 tag 发布的可执行贡献路径并能理解其背后由 Makefile、GitHub Actions 工作流与配置生成脚本共同构成的工程化支撑。前置约定参与即代表认同行为准则在开始任何贡献之前请注意参与 golangci-lint 项目即表示你同意遵守项目的行为准则Code of Conduct。这一点在官方贡献工作流文档 docs/content/docs/contributing/workflow.md 的开篇即被明确声明。若你在贡献过程中遇到任何违反准则的行为应通过项目维护渠道反馈而不是自行处理。环境准备一台可以构建 golangci-lint 的机器golangci-lint 使用 Go 语言编写因此在本地开发前需要满足以下前置条件make项目几乎所有构建、测试、文档生成任务都由 Makefile 驱动Go需安装与仓库go.mod要求兼容的 Go 工具链版本。环境就绪后第一步是 fork 并 clone golangci-lint 仓库。建议使用以下方式验证本机环境是否一切正常make build ./golangci-lint run -vmake build会调用 Makefile 中的build目标执行go build -o golangci-lint ./cmd/golangci-lint见 Makefile在仓库根目录产出名为golangci-lint的二进制文件Windows 下为golangci-lint.exe见 Makefile./golangci-lint run -v使用刚构建出的二进制对当前仓库自身执行一次完整的 lint 检查并开启-v详细输出。这一步既是环境自检也是dogfooding——用项目自己检查自己。如果这两条命令都能顺利通过说明构建链与 Go 环境配置正确可以开始编码了。附带了解Makefile 提供的其他常用目标除了build根目录 Makefile 中还提供了与开发验证密切相关的目标贡献者在不同场景下会用到build_race以-race竞态检测模式构建用于排查并发问题test默认目标先构建再对仓库执行 lint 与全量单元测试详见下文测试你的变更test_race以竞态检测模式运行 lint 与测试test_integration/test_integration_fix针对test/testdata下指定文件的集成测试例如Toutput.go make test_integration。测试你的变更make test一站式验证当你对代码改动感到满意后官方工作流建议运行make test该命令runs all the linters and tests运行全部 linter 与测试。查看 Makefile 可以看到其具体行为test: export GOLANGCI_LINT_INSTALLED true test: CGO_ENABLED1 test: build GL_TEST_RUN1 ./$(BINARY) run -v GL_TEST_RUN1 go test -v -parallel 2 ./...即make test会依次完成以CGO_ENABLED1构建最新二进制用该二进制对仓库自身跑一遍完整 lintGL_TEST_RUN1 ./golangci-lint run -v保证新代码本身不引入 lint 问题运行全量 Go 单元测试go test -v -parallel 2 ./...覆盖pkg、internal、test等全部包。提示GL_TEST_RUN1环境变量用于标记正在被 golangci-lint 自身测试的运行场景在仓库测试代码中有对应的行为分支避免测试与自检相互干扰。集成测试覆盖了大量真实场景例如test/testdata下按 linter 组织的示例代码与期望输出以及 test/run_test.go、test/linters_test.go 等针对整体运行流程的测试。若你的改动影响某个具体 linter 的输出格式对应的*_integration_test.go分布在 pkg/golinters 各子目录中会是验证重点。更新文档参数写入.golangci.next.reference.yml如果你在贡献中新增或修改了配置参数例如为某个 linter 增加新的设置项必须同步更新仓库根目录下的 .golangci.next.reference.yml 文件。这份文件是下一版本的完整配置参考包含所有可用配置项及其默认值以注释形式标注例如# This file contains all available configuration options # with their default values (in comments). # # This file is not a configuration example, # it contains the exhaustive configuration with explanations of the options. # Defines the configuration version. # The only possible value is 2. version: 2 linters: # Default set of linters. # The value can be: # - standard: the Default linters # - all: enables all linters by default. # - none: disables all linters by default. # - fast: enables only linters considered as fast default: all从仓库现状看该文件超过 5000 行是文档站配置章节的数据来源之一。其命名中的next表明它面向下一个未发布版本新参数先在此登记待版本发布后才会固化到正式参考文件并展现在官方文档中。因此新增或变更参数是每个涉及配置的 PR 的必备环节遗漏将导致文档与实际行为不一致。创建 Discussion开 PR 之前的第一步golangci-lint 项目要求在打开 Pull Request 之前必须先创建 Discussion讨论帖。这是硬性前置流程尤其对于新 linter 的提议。项目为不同主题设置了讨论分类其中为新增 linter 专门设立了 New Linter Proposals 分类。仓库中对应提供了讨论模板 .github/DISCUSSION_TEMPLATE/new-linter-proposals.yml用于规范新 linter 提案的信息结构此外还有配套的检查清单 .github/new-linter-checklist.md帮助提案者与维护者逐项核对新增 linter 的完整性要求。如果你计划新增 linter建议同时阅读 docs/content/docs/contributing/new-linters.md了解添加一个 linter 所涉及的内部结构pkg/golinters下的实现、pkg/lint/lintersdb中的注册、测试与文档——这些都属于工作流的延伸准备能显著提高提案被接受的概率。提交 Pull Request基于main分支当维护者在 Discussion 中批准了你的提案尤其是 linter 提案后就可以进入提交阶段将你的功能分支推送到 fork 仓库在 golangci-lint 原仓库针对main分支打开 Pull Request。仓库提供了 PR 模板 .github/PULL_REQUEST_TEMPLATE.md提交前应参照模板填写变更说明、测试情况与相关讨论链接。PR 检查CLA 与 CI 自动化PR 打开后有两类检查需要关注CLA 签署首先需要接受 Contributor License Agreement贡献者许可协议。CLA assistant 会在 PR 上自动发表评论提示签署。未签署 CLA 的 PR 不会被合并。GitHub Actions CI 检查项目通过 GitHub Actions 运行多组 CI 检查工作流定义集中在 .github/workflows 目录与本流程直接相关的包括pr-checks.ymlPR 基础检查构建、生成产物一致性等pr-tests.yml运行测试套件pr-documentation.yml校验文档与配置参考的同步性new-linter-checklist.yml针对新 linter 的自动化清单校验codeql.yml代码安全静态分析。这意味着一个合规的 PR 不仅代码要正确还需要通过格式、lint、生成文件一致性、文档同步等多维度的机器检查。建议在本地完整执行make test后再提交尽量把问题挡在 CI 之前。新版本发布tag 触发 自动化流水线发布流程同样由工作流文档给出明确指引并与仓库内的版本策略、工作流脚本严格对应。版本策略理解何时升 minor / patch / major在发布之前请先阅读版本策略文档 docs/content/docs/product/roadmap.md原工作流文档以our versioning policy指代。其核心结论是 golangci-lint 遵循语义化版本SemVer但结合代码质量工具的特性做了细化约定Patch 版本预期不破坏你的 lint 构建单个 linter 的 patch 级更新导致报错减少、CLI 或核心包加载、runner、后处理器等的 bug 修复、文档改进、非面向用户的内部重构与测试调整、失败发布的重新发布Minor 版本可能因新发现的问题破坏 lint 构建linter 的 minor/major 更新导致报错增多、新增 linter、弃用某个配置项或 linter、新增 CLI 命令、配置的向后不兼容变更Major 版本大概率破坏 lint 构建影响面巨大的向后不兼容配置变更。基于该策略任何 minor 更新都可能比前一版本报告更多问题因此官方建议固定 minor 版本号、同时允许 patch 版本浮动以保证构建结果可控官方 GitHub Action 即采用此策略。创建 tag 触发发布发布操作本身非常简单创建形如vX.Y.Z的 tag新 minor 版本必须带上零 patch 号例如v1.99.0而不是v1.99——这与 scripts/gen_github_action_config/main.go 中的版本解析逻辑parseVersion同时支持 2 段与 3 段版本号但规范发布要求 3 段完整版本保持一致推送 tag 后GitHub Actions 的 release.yml 工作流会自动触发on: push: tags: [v*]使用 goreleaser 完成多平台构建、容器镜像发布、SBOM 与 attestation 生成等一系列发布动作最终产出 GitHub Release 并同步到各分发渠道。发布后更新 Action 配置Release 发布完成后还需要更新 GitHub Action 的版本映射配置。工作流文档给出了明确命令make assets/github-action-config.json该命令对应 Makefile 中的目标实际执行的是scripts/gen_github_action_config目录下的 Go 程序assets/github-action-config.json: FORCE $(BINARY) cd ./scripts/gen_github_action_config/; go run . ../../$从 scripts/gen_github_action_config/main.go 的源码可以看到该程序会通过 GitHub GraphQL API 拉取全部 release需要GITHUB_TOKEN环境变量见fetchAllReleases为每个 minor 版本计算对应的最大 patch 版本并生成版本 → 可下载资产 URL的映射buildConfig分别产出github-action-config.json、github-action-config-v1.json仅兼容 v1 系列最低支持 v1.28.3与github-action-config-v2.jsonv2 系列仓库 assets 目录中的三个 JSON 文件即该脚本的输出结果。这样golangci-lint-action就能根据用户指定的 minor 版本自动解析到最新的 patch 版本并下载对应二进制实现固定 minor、滚动 patch的版本策略落地。更多贡献主题的延伸阅读工作流文档之外docs/content/docs/contributing 目录还提供了与贡献流程配套的专题文档可作为深度参与的下一步architecture.mdgolangci-lint 的整体架构包加载、runner、后处理器、输出器如何协作new-linters.md新增 linter 的完整实现指南debug.md调试 golangci-lint 运行过程的方法faq.md贡献过程中的常见问题website.md参与文档站本身建设的规范。总结golangci-lint 的贡献工作流可以浓缩为一条清晰的链路搭建环境并自检 → 修改代码 →make test验证 → 同步.golangci.next.reference.yml→ 先 Discussion 后 PR → 通过 CLA 与 CI 检查 → 合并发布时则遵循 SemVer 细化策略打 tag由 release.yml 自动构建最后通过make assets/github-action-config.json更新 Action 版本映射。每个环节都有仓库内的 Makefile 目标、工作流文件或生成脚本作为可验证的支撑照此流程操作即可让贡献过程与项目维护者的预期完全对齐。【免费下载链接】golangci-lintFast linters runner for Go项目地址: https://gitcode.com/gh_mirrors/go/golangci-lint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考