如何为 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/ 下的三个文件，这会大幅降低你贡献代码的难度：
| 文件 | 职责 | 你会在这里做什么 |
|---|---|---|
| highlight.rs | 全部高亮组定义（约 800 行） | 新增/调整某个语法高亮或插件主题 |
| conv.rs | 颜色转换工具 | 一般不用改，了解即可 |
| main.rs | CLI 入口与文件写出 | 一般不用改，了解即可 |
高亮定义采用宏 DSL，例如hi!("Comment", commentfg, -, -, None, -);，颜色语义清晰（紫蓝=关键字、绿=字符串、青=常量），读起来非常直观。
第三步：快速上手一个真实改动
假设你想新增一个插件的主题适配，流程如下：
- 在 highlight.rs 中新增高亮组，使用
hi!()宏并挑选合适的语义色。 - 重新生成配色文件：
cd generator just build # 等价于 cargo run -- -d ..- 检查生成结果是否符合预期：
git diff ../colors/dogrun.vim- 在 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 了。推荐这样组织提交：
- 分开提交源码与产物：源码改动一个 commit，重新生成的
.vim文件一个 commit，方便维护者 review。 - 写清楚 PR 描述：说明改了什么、为什么改、贴一张改动后的配色效果图（图片胜千言）。
- 更新 README：如果你新增了插件支持，记得同步 README.md 中的插件列表，它也是仓库规范的一部分。
第六步：从 Push 到通过 CI 的完整流程
推送分支后，.github/workflows/ci.yaml 会自动触发名为Build and Test的流水线，共 6 道关卡，全部通过才算绿：
- Check formatting：
cargo fmt --check，代码格式不符合 rustfmt 规范会直接失败。 - Run clippy：
cargo clippy --all-targets --all-features -- -D warnings，严格模式，任何警告都会视为错误。 - Build：以 release 模式编译整个生成器，确保产物可发布。
- Run tests：执行
cargo test，验证 fzf、README 等集成测试全部通过。 - Check generator is up-to-date（最容易翻车的一步）：CI 会运行
cargo run -- -d ..重新生成文件，然后git diff比对colors/与autoload/。只要生成结果与已提交文件不一致，这一步就会失败——这就是为什么"永远记得提交生成文件"。 - 缓存加速：CI 用
actions/cache缓存 cargo 依赖与构建产物，同一次提交的依赖只编译一次，等待时间并不长。
常见 CI 失败原因与解决办法速查
| 失败现象 | 大概率原因 | 解决办法 |
|---|---|---|
| fmt 检查失败 | 代码未格式化 | 运行just fmt后重新提交 |
| clippy 报 warning | 存在未被消除的警告 | 按提示修复，直到零警告 |
| 测试失败 | 逻辑改动影响既有断言 | 阅读 generator/tests/ 中的用例定位问题 |
| "Generated files are not up-to-date" | 改了源码但没重新生成/提交产物 | 运行just build，提交colors/与autoload/下的变更 |
结语：你的第一次贡献其实很简单
为 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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
