如何为 vim-dogrun 贡献代码？从提交 PR 到通过 CI 的完整流程

如何为 vim-dogrun 贡献代码？从提交 PR 到通过 CI 的完整流程

【免费下载链接】vim-dogrun:dog: A dark Neovim / Vim colorscheme for the GUI and 256 / true-color terminals.项目地址: https://gitcode.com/gh_mirrors/vi/vim-dogrun

想为vim-dogrun 贡献代码却不知从何下手？这篇面向新手的完整贡献指南，将带你走通从克隆仓库、修改 Rust 源码、生成配色文件，到提交 PR 并通过 CI 检查的全流程。vim-dogrun 是一款支持 GUI、256 色与 true-color 终端的深色 Neovim / Vim 配色方案，它的特别之处在于：所有配色文件都由一个 Rust 生成器产出，理解这套架构后，你的贡献会变得又快又稳。

为什么值得为 vim-dogrun 贡献代码？先认识这个项目

vim-dogrun 不是一份手写的.vim文件，而是一个"生成器 + 产物"的双层架构：

• 源码（你来改的部分）：Rust 生成器，位于 generator/，核心是 highlight.rs（全部高亮组定义）和 conv.rs（Hex → LAB → 256 色的转换工具）。
• 产物（不要手改的部分）：colors/dogrun.vim、autoload/lightline/colorscheme/dogrun.vim、autoload/clap/themes/dogrun.vim等，全部由生成器自动写出。

项目内置了 50+ 插件的主题适配，并支持 nvim-treesitter、LSP Semantic 高亮。下面是它在 Neovim 和 Vim 中的实际效果：

📌 黄金规则：永远不要直接编辑生成文件。修改 Rust 源码后重新生成，再提交生成结果，这是让 CI 通过的关键前提。

第一步：克隆仓库并搭建本地环境

把仓库克隆到本地：

git clone https://gitcode.com/gh_mirrors/vi/vim-dogrun cd vim-dogrun

生成器依赖 Rust 工具链，建议用项目自带的 mise.toml 统一管理just（任务执行器）和bacon（热重载工具）：

cd generator mise install

如果还没有安装 mise 或 Rust，请先安装对应工具链（rustup 安装 stable 版本即可）。

第二步：掌握生成器的三个核心文件

开工前，花两分钟认识 generator/src/ 下的三个文件，这会大幅降低你贡献代码的难度：

高亮定义采用宏 DSL，例如hi!("Comment", commentfg, -, -, None, -);，颜色语义清晰（紫蓝=关键字、绿=字符串、青=常量），读起来非常直观。

第三步：快速上手一个真实改动

假设你想新增一个插件的主题适配，流程如下：

1. 在 highlight.rs 中新增高亮组，使用hi!()宏并挑选合适的语义色。
2. 重新生成配色文件：

cd generator just build # 等价于 cargo run -- -d ..

3. 检查生成结果是否符合预期：

git diff ../colors/dogrun.vim

4. 在 Vim / Neovim 中实测效果：

nvim -c "colorscheme dogrun"

💡 小技巧：just watch会启动 bacon 热重载模式，改完 Rust 代码自动重新生成，非常适合反复调色的场景。

第四步：提交 PR 前，先在本地跑一遍完整检查

CI 里跑的每一条检查，本地都能提前执行。在generator/目录下运行：

just check

它等价于：

just lint # cargo fmt --check + cargo clippy -- -D warnings just test # cargo test

其中测试套件位于 generator/tests/，例如fzf_generation.rs会校验 fzf 色板的格式与必备色键，readme_update.rs会验证 README 中 fzf 配置片段能被正确更新且不破坏周边内容——修改 README 相关逻辑时，这些测试就是你最好的护身符。

别忘了最后一次just build并提交生成文件，否则 CI 会在最后一步直接拦截你。

第五步：提交 PR 的正确姿势

本地检查全部通过后，就可以提交代码并发起 PR 了。推荐这样组织提交：

1. 分开提交源码与产物：源码改动一个 commit，重新生成的.vim文件一个 commit，方便维护者 review。
2. 写清楚 PR 描述：说明改了什么、为什么改、贴一张改动后的配色效果图（图片胜千言）。
3. 更新 README：如果你新增了插件支持，记得同步 README.md 中的插件列表，它也是仓库规范的一部分。

第六步：从 Push 到通过 CI 的完整流程

推送分支后，.github/workflows/ci.yaml 会自动触发名为Build and Test的流水线，共 6 道关卡，全部通过才算绿：

1. Check formatting：cargo fmt --check，代码格式不符合 rustfmt 规范会直接失败。
2. Run clippy：cargo clippy --all-targets --all-features -- -D warnings，严格模式，任何警告都会视为错误。
3. Build：以 release 模式编译整个生成器，确保产物可发布。
4. Run tests：执行cargo test，验证 fzf、README 等集成测试全部通过。
5. Check generator is up-to-date（最容易翻车的一步）：CI 会运行cargo run -- -d ..重新生成文件，然后git diff比对colors/与autoload/。只要生成结果与已提交文件不一致，这一步就会失败——这就是为什么"永远记得提交生成文件"。
6. 缓存加速：CI 用actions/cache缓存 cargo 依赖与构建产物，同一次提交的依赖只编译一次，等待时间并不长。

常见 CI 失败原因与解决办法速查

结语：你的第一次贡献其实很简单

为 vim-dogrun 贡献代码的秘诀只有一句话：改 Rust 源码，用just build重新生成，提交前跑just check，并永远带上生成的产物。只要遵循这条路径，CI 的绿色对勾几乎唾手可得。从修正一个高亮颜色、适配一个新插件开始，你的第一个 PR 很快就会出现在合并列表里。快去试试吧！🚀

【免费下载链接】vim-dogrun:dog: A dark Neovim / Vim colorscheme for the GUI and 256 / true-color terminals.项目地址: https://gitcode.com/gh_mirrors/vi/vim-dogrun