doc: add README for gomodcheck

qiniu · Sep 15, 2024 · a7a3988 · a7a3988
1 parent 0b4cde2
commit a7a3988
Show file tree

Hide file tree

Showing 16 changed files with 59 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -27,6 +27,7 @@ If you are facing similar challenges, we welcome you to try **Reviewbot**!
 - go linters
   - [golangci-lint](/internal/linters/go/golangci_lint/)
   - [gofmt](/internal/linters/go/gofmt/)
+  - [gomodcheck](/internal/linters/go/gomodcheck/)
 - c/c++ linters
   - [cppcheck](/internal/linters/c/cppcheck/)
 - lua linters

diff --git a/README_zh.md b/README_zh.md
@@ -27,6 +27,7 @@
 - go linters
   - [golangci-lint](/internal/linters/go/golangci_lint/)
   - [gofmt](/internal/linters/go/gofmt/)
+  - [gomodcheck](/internal/linters/go/gomodcheck/)
 - c/c++ linters
   - [cppcheck](/internal/linters/c/cppcheck/)
 - lua linters

diff --git a/docs/website/docs/components/_category_.json b/docs/website/docs/components/_category_.json
@@ -1,6 +1,7 @@
 {
   "label": "Linters",
   "position": 3,
+  "collapsed": false,
   "link": {
     "type": "generated-index",
     "description": "我们来了解 Reviewbot 目前已有的功能！"

diff --git a/docs/website/docs/components/go/gomodcheck.md b/docs/website/docs/components/go/gomodcheck.md
@@ -0,0 +1,34 @@
+---
+title: gomodcheck
+sidebar_position: 3
+---
+
+`gomodcheck` 是一个专门用于检查 Go 项目中 `go.mod` 文件的 linter。它的主要目的是限制跨仓库的 local replace 使用，以确保项目依赖管理的一致性和可重现性。
+
+比如:
+
+```go
+replace github.com/qiniu/go-sdk/v7 => ../another_repo/src/github.com/qiniu/go-sdk/v7
+```
+
+`../another_repo` 代表当前仓库的父目录下的 `another_repo` 目录. 这种用法非常的不推荐.
+
+### 为什么要限制跨仓库的 local replace？
+
+1. **可重现性**: 跨仓库的 local replace 使得构建过程依赖于本地文件系统结构，这可能导致不同环境下的构建结果不一致。
+
+2. **依赖管理**: 它绕过了正常的依赖版本控制，可能引入未经版本控制的代码。
+
+3. **协作困难**: 其他开发者或 CI/CD 系统可能无法访问本地替换的路径，导致构建失败。
+
+4. **版本跟踪**: 使用 local replace 难以追踪依赖的具体版本，增加了项目维护的复杂性。
+
+### 这种情况推荐怎么做？
+
+尽可能使用正式发布的依赖版本, 即使是 private repo 也是一样的。
+
+:::info
+
+可以使用 go env -w GOPRIVATE 来设置私有仓库, 方便 go mod 下载依赖.
+
+:::
diff --git a/docs/website/docusaurus.config.ts b/docs/website/docusaurus.config.ts
@@ -83,6 +83,12 @@ const config: Config = {
       theme: prismThemes.github,
       darkTheme: prismThemes.dracula,
     },
+    docs: {
+      sidebar: {
+        hideable: true,
+        autoCollapseCategories: true,
+      },
+    },
   } satisfies Preset.ThemeConfig,
 };
 

diff --git a/docs/website/sidebars.ts b/docs/website/sidebars.ts
@@ -12,8 +12,12 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
  */
 const sidebars: SidebarsConfig = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
-  tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],
-
+  tutorialSidebar: [
+    {
+      type: 'autogenerated',
+      dirName: '.',
+    },
+  ],
 };
 
 export default sidebars;
diff --git a/internal/linters/doc/note-check/README.md b/internal/linters/doc/note-check/README.md
@@ -0,0 +1 @@
+see [note-check](../../../../docs/website/docs/components/doc/note-check.md)
diff --git a/internal/linters/git-flow/commit-check/README.md b/internal/linters/git-flow/commit-check/README.md
@@ -0,0 +1 @@
+see [commit-check](../../../../docs/website/docs/components/git-flow/commit-check.md)
diff --git a/internal/linters/go/gofmt/README.md b/internal/linters/go/gofmt/README.md
@@ -0,0 +1 @@
+see [gofmt](../../../../docs/website/docs/components/go/gofmt.md)
diff --git a/internal/linters/go/golangci_lint/README.md b/internal/linters/go/golangci_lint/README.md
@@ -0,0 +1 @@
+see [golangci_lint](../../../../docs/website/docs/components/go/golangci_lint.md)
diff --git a/internal/linters/go/gomodcheck/README.md b/internal/linters/go/gomodcheck/README.md
@@ -0,0 +1 @@
+see [gomodcheck](../../../../docs/website/docs/components/go/gomodcheck.md)
diff --git a/internal/linters/go/staticcheck/README.md b/internal/linters/go/staticcheck/README.md
@@ -0,0 +1 @@
+see [staticcheck](../../../../docs/website/docs/components/go/staticcheck.md)
diff --git a/internal/linters/java/pmdcheck/README.md b/internal/linters/java/pmdcheck/README.md
@@ -0,0 +1 @@
+see [pmdcheck](../../../../docs/website/docs/components/java/pmdcheck.md)
diff --git a/internal/linters/java/stylecheck/README.md b/internal/linters/java/stylecheck/README.md
@@ -0,0 +1 @@
+see [stylecheck](../../../../docs/website/docs/components/java/stylecheck.md)
diff --git a/internal/linters/lua/luacheck/README.md b/internal/linters/lua/luacheck/README.md
@@ -0,0 +1 @@
+see [luacheck](../../../../docs/website/docs/components/lua/luacheck.md)
diff --git a/internal/linters/shell/shellcheck/README.md b/internal/linters/shell/shellcheck/README.md
@@ -0,0 +1 @@
+see [shellcheck](../../../../docs/website/docs/components/shell/shellcheck.md)