尧图网页设计 
telescope.nvim 贡献指南从贡献策略到 docgen 文档自动生成工作流【免费下载链接】telescope.nvimFind, Filter, Preview, Pick. All lua, all the time.项目地址: https://gitcode.com/GitHub_Trending/te/telescope.nvimtelescope.nvim 是构建在 Neovim 核心特性之上、以 Lua 编写的高度可扩展模糊查找插件Find, Filter, Preview, Pick. All lua, all the time.。本文基于仓库根目录的 CONTRIBUTING.md 编写系统梳理该项目面向贡献者的准入策略、扩展化打包路线、Issue/PR 协作规范以及文档即代码的 emmylua 注解与 docgen 自动生成工作流。读完本文你将掌握如何判断一个改动是否会被 telescope.nvim 社区接受、如何将自定义 picker 打包成扩展、以及如何让文档与代码保持同步并通过 CI 校验。一、贡献总览项目欢迎什么、暂不接受什么telescope.nvim 欢迎社区参与其 CONTRIBUTING.md 开篇即表明态度非常欢迎新贡献者也乐见 Neovim 社区围绕该插件持续改进。但与此同时项目对内置 picker 的增量持明确的保守立场这是理解整个贡献流程的前提暂不接受新的内置 picker项目认为目前内置 picker 的数量与功能已经足够处于 content with the number and functionality 的状态因此不再接纳新的 builtin picker相关讨论可查阅仓库文档中引用的 issue 讨论。对 picker 专属动作picker specific actions与特性的整合同样保守即使功能合理维护者也倾向于不将其并入核心内置实现。明确欢迎的贡献类型Bug 修复bug fixes、文档改进documentation improvements、以及非 picker 专属的特性non-picker specific features。这一策略背后的工程考量可以从仓库结构得到印证内置 picker 全部集中在 lua/telescope/builtin/ 目录其入口 lua/telescope/builtin/init.lua 承载 find_files、live_grep、buffers 等数十个内置函数任何新增都会直接扩大核心 API 的长期维护面。因此项目给出的官方建议是如果你的需求确实需要一个新的 picker请将其打包为独立的 telescope 扩展extension而不是提交进核心仓库。二、新 picker 需求的正确姿势打包为扩展如果你仍想填补某个 picker 需求CONTRIBUTING.md 明确指引读者阅读开发者文档中的 Bundling as extension 一节见仓库根目录 developers.md把自定义 picker 以扩展形式发布。这样既服务了有同样需求的用户又不增加核心仓库的维护负担。2.1 扩展的目录结构约定按 developers.md 的说明插件需要按如下结构组织才能被 telescope 的扩展管理器发现. └── lua ├── plugin_name # 你的插件实际代码 │ ├── init.lua │ └── some_file.lua └── telescope └── _extensions # 下划线前缀是约定的必须有 └─ plugin_name.lua # 初始化并注册你的扩展其中lua/telescope/_extensions/plugin_name.lua文件需要调用register_extension返回一个扩展描述表return require(telescope).register_extension { setup function(ext_config, config) -- 访问扩展自身的配置与用户全局配置 end, exports { stuff require(plugin_name).stuff }, }各字段的语义可以从核心实现 lua/telescope/_extensions/init.lua 中确认setup(ext_config, config)扩展首次加载时被调用。第一个参数是用户在telescope.setup{ extensions {...} }中传入的该扩展配置第二个参数是用户应用完 setup 默认值之后的全局配置config.values。官方允许扩展覆盖 config 中的值——有些插件存在的意义就是管理某类配置、安装某个 sorter 等。exportstable只有exports中的条目会被暴露到用户可访问的require(telescope).extensions.foo模块上。此外exports中键不以_开头且值为函数的条目还会在builtinpicker 开启include_extensions选项时被纳入内置 picker 列表。这就是扩展的公开 API开发者被建议保持其稳定。setup函数之所以能拿到用户配置、甚至覆盖排序器是因为 lua/telescope/_extensions/init.lua 中的加载逻辑extensions.manager通过__index元方法在首次访问时pcall(require, telescope._extensions. .. name)惰性加载扩展并立即调用其setup。因此类似 telescope-fzf-native 这类替换默认 sorter的扩展正是在setup阶段完成对内部排序函数的覆写。2.2 扩展的安装与调用扩展装好后用户侧的使用方式有两种见 README.md-- Lua 方式加载并覆盖默认文件 sorter require(telescope).load_extension(fzy_native) 命令方式通过 :Telescope 调用扩展导出的 picker Telescope dap configurations 也可以直接以 Lua 调用 :lua require(telescope).extensions.dap.configurations()值得注意的细节是如果跳过显式load_extension扩展会被惰性加载但:Telescope的 Tab 补全不会立即可用。而在extensions {}配置块中传入的配置正是setup(ext_config, ...)收到的第一个参数由extensions.set_config写入_config表。三、提交规范Issue 先行与 PR 模板3.1 新特性先开 IssueCONTRIBUTING.md 建议提交新特性前最好先创建 issue 以评估社区兴趣与可行性it is a good idea to create an issue first to gauge interest and feasibility。这与仓库的 .github/ISSUE_TEMPLATE/ 模板体系相互配套.github/ISSUE_TEMPLATE/bug_report.yml结构化 Bug 报告表单强制填写 Description、nvim --version输出、操作系统版本、telescope 版本、:checkhealth telescope输出、复现步骤、期望/实际行为并内置一份可独立运行的 minimal config基于 lazy.nvim 自举隔离用户环境仅保留复现所需的依赖。.github/ISSUE_TEMPLATE/feature_request.md功能请求模板要求描述问题背景、期望的解决方案、替代方案及附加上下文。3.2 PR 模板与自查清单.github/PULL_REQUEST_TEMPLATE.md 要求每个 PR 说明改动摘要与修复的 issue 编号、变更类型Bug 修复 / 新特性 / 破坏性变更 / 需要文档更新、测试方式与复现步骤、环境信息。其 Checklist 与本仓库的工程规范直接相关代码风格遵循 stylua完成了自我 review在难理解处添加了注释对文档做了相应修改lua annotations——这一项与下文的 docgen 工作流直接呼应。四、文档即代码emmylua 注解与make docgen这是 CONTRIBUTING.md 中唯一以 ## 开头的独立章节也是该项目贡献流程中最具特色的部分The docs are generated from the code using emmylua annotations. To update them after making changes to the code, runmake docgen. A Check docs workflow in CI ensures that the documentation matches any change to the code and its annotations.即项目文档doc/telescope.txt等不是手写维护的而是从源码中的 emmylua 注解自动生成的。4.1 注解从何而来在核心入口 lua/telescope/init.lua 中可以直观看到这类注解---brief用于生成文档开篇简介包括一张纯文本绘制的 telescope 架构图---eval return require(telescope).__format_setup_keys()动态求值生成setup()的全部默认键文档---param opts table: Configuration opts. Keys: defaults, pickers, extensions声明函数参数类型。同理setup、load_extension、register_extension等公开 API 均通过注解在:help中呈现。4.2 docgen 如何工作make docgen由根目录 Makefile 定义.deps/docgen.nvim: git clone --depth 1 --branch v1.1.0 https://github.com/jamestrew/docgen.nvim $ docgen: .deps/docgen.nvim nvim -l scripts/gendocs.lua它先克隆固定版本v1.1.0的 docgen.nvim 到.deps/再以无头模式执行 scripts/gendocs.lua。后者将项目根、plenary 与 docgen.nvim 加入 rtp然后调用require(docgen).run{...}其files表一一映射了源码模块与文档章节标题例如lua/telescope/init.lua→INTRODUCTIONtagtelescope.nvimlua/telescope/command.lua、lua/telescope/builtin/init.lua、lua/telescope/themes.lua、lua/telescope/mappings.lua→ 对应帮助章节lua/telescope/pickers/layout.lua→LAYOUTtagtelescope.layoutlua/telescope/pickers/layout_strategies.lua→LAYOUT_STRATEGIESlua/telescope/config/resolve.lua→RESOLVE以及make_entry.lua、entry_display.lua、utils.lua、actions/系列、previewers/init.lua等也就是说凡是被列入files表的模块其公开函数的 emmylua 注解都会进入:help telescope.*。贡献者新增或修改 API 时必须同步更新注解并重新运行make docgen才能让doc/telescope.txt反映真实代码。4.3 CI 如何强制文档与代码同步.github/workflows/docgen.yml 实现了名为 Check docs 的 CI 检查在 ubuntu-latest 上安装最新 stable Neovim、克隆 plenary 并将当前仓库软链接到 packpath然后执行make docgen与git diff --exit-code。任何代码或注解变更若未同步重新生成文档diff 就会非空CI 直接失败。这正是 CONTRIBUTING.md 所说 ensures that the documentation matches any change to the code and its annotations 的落地实现也是 PR 模板中已对文档lua annotations做出相应修改勾选项被强制的原因。五、质量保障测试与 lint除了文档校验贡献者的改动还会经过完整的测试与静态检查相关入口同样集中在根目录 Makefiletest: nvim --headless --noplugin -u scripts/minimal_init.vim -c PlenaryBustedDirectory lua/tests/automated/ { minimal_init ./scripts/minimal_init.vim } lint: luacheck lua/telescopemake test以无头模式启动 Neovim加载 scripts/minimal_init.vim用 plenary 的 Busted 目录运行 lua/tests/automated/ 下的全部自动化测试覆盖 find_files、live_grep、action、sorter、layout_strategies、entry_display、resolver、scroller 等模块测试实现见 lua/tests/helpers.lua。make lint使用 luacheck 对 lua/telescope 全目录做静态检查。.github/workflows/ci.yml 将make test部署到 ubuntu / macos / windows 三个平台并在 nightly 与 stable 两个 Neovim 版本上各跑一遍同时安装 ripgrep 以满足 live_grep 类测试的外部依赖。因此贡献者提交前最好先在本地跑通make test与make lint。六、贡献者行动清单综合 CONTRIBUTING.md、Makefile、.github/ 下的模板与工作流一个符合 telescope.nvim 社区预期的贡献流程可以总结为判断归属新 picker 需求优先打包为扩展结构见 developers.md 的 Bundling as extensionBug 修复、文档改进、非 picker 特性欢迎直接进入核心仓库。先讨论后动手新特性先开 issue参考 .github/ISSUE_TEMPLATE/feature_request.md评估可行性Bug 报告按 .github/ISSUE_TEMPLATE/bug_report.yml 提供最小复现配置。代码与注解同行修改公开 API 时同步更新对应 Lua 文件的 emmylua 注解并运行make docgen重新生成 doc/telescope.txt 等帮助文档。本地验证运行make test与make lint确保改动通过自动化测试与静态检查PR 中按 .github/PULL_REQUEST_TEMPLATE.md 填写变更类型、测试方式与 checklist。这套流程的核心思想是以文档一致性作为代码合入的门禁通过 emmylua 注解 docgen CI diff 检查让:help telescope永远与源码保持同步同时用保守的准入策略把核心仓库的长期维护面控制住把更丰富的 picker 生态留给扩展体系去承载。【免费下载链接】telescope.nvimFind, Filter, Preview, Pick. All lua, all the time.项目地址: https://gitcode.com/GitHub_Trending/te/telescope.nvim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 telescope.nvim 贡献指南：从贡献策略到 docgen 文档自动生成工作流
telescope.nvim 贡献指南从贡献策略到 docgen 文档自动生成工作流【免费下载链接】telescope.nvimFind, Filter, Preview, Pick. All lua, all the time.项目地址: https://gitcode.com/GitHub_Trending/te/telescope.nvimtelescope.nvim 是构建在 Neovim 核心特性之上、以 Lua 编写的高度可扩展模糊查找插件Find, Filter, Preview, Pick. All lua, all the time.。本文基于仓库根目录的 CONTRIBUTING.md 编写系统梳理该项目面向贡献者的准入策略、扩展化打包路线、Issue/PR 协作规范以及文档即代码的 emmylua 注解与 docgen 自动生成工作流。读完本文你将掌握如何判断一个改动是否会被 telescope.nvim 社区接受、如何将自定义 picker 打包成扩展、以及如何让文档与代码保持同步并通过 CI 校验。一、贡献总览项目欢迎什么、暂不接受什么telescope.nvim 欢迎社区参与其 CONTRIBUTING.md 开篇即表明态度非常欢迎新贡献者也乐见 Neovim 社区围绕该插件持续改进。但与此同时项目对内置 picker 的增量持明确的保守立场这是理解整个贡献流程的前提暂不接受新的内置 picker项目认为目前内置 picker 的数量与功能已经足够处于 content with the number and functionality 的状态因此不再接纳新的 builtin picker相关讨论可查阅仓库文档中引用的 issue 讨论。对 picker 专属动作picker specific actions与特性的整合同样保守即使功能合理维护者也倾向于不将其并入核心内置实现。明确欢迎的贡献类型Bug 修复bug fixes、文档改进documentation improvements、以及非 picker 专属的特性non-picker specific features。这一策略背后的工程考量可以从仓库结构得到印证内置 picker 全部集中在 lua/telescope/builtin/ 目录其入口 lua/telescope/builtin/init.lua 承载 find_files、live_grep、buffers 等数十个内置函数任何新增都会直接扩大核心 API 的长期维护面。因此项目给出的官方建议是如果你的需求确实需要一个新的 picker请将其打包为独立的 telescope 扩展extension而不是提交进核心仓库。二、新 picker 需求的正确姿势打包为扩展如果你仍想填补某个 picker 需求CONTRIBUTING.md 明确指引读者阅读开发者文档中的 Bundling as extension 一节见仓库根目录 developers.md把自定义 picker 以扩展形式发布。这样既服务了有同样需求的用户又不增加核心仓库的维护负担。2.1 扩展的目录结构约定按 developers.md 的说明插件需要按如下结构组织才能被 telescope 的扩展管理器发现. └── lua ├── plugin_name # 你的插件实际代码 │ ├── init.lua │ └── some_file.lua └── telescope └── _extensions # 下划线前缀是约定的必须有 └─ plugin_name.lua # 初始化并注册你的扩展其中lua/telescope/_extensions/plugin_name.lua文件需要调用register_extension返回一个扩展描述表return require(telescope).register_extension { setup function(ext_config, config) -- 访问扩展自身的配置与用户全局配置 end, exports { stuff require(plugin_name).stuff }, }各字段的语义可以从核心实现 lua/telescope/_extensions/init.lua 中确认setup(ext_config, config)扩展首次加载时被调用。第一个参数是用户在telescope.setup{ extensions {...} }中传入的该扩展配置第二个参数是用户应用完 setup 默认值之后的全局配置config.values。官方允许扩展覆盖 config 中的值——有些插件存在的意义就是管理某类配置、安装某个 sorter 等。exportstable只有exports中的条目会被暴露到用户可访问的require(telescope).extensions.foo模块上。此外exports中键不以_开头且值为函数的条目还会在builtinpicker 开启include_extensions选项时被纳入内置 picker 列表。这就是扩展的公开 API开发者被建议保持其稳定。setup函数之所以能拿到用户配置、甚至覆盖排序器是因为 lua/telescope/_extensions/init.lua 中的加载逻辑extensions.manager通过__index元方法在首次访问时pcall(require, telescope._extensions. .. name)惰性加载扩展并立即调用其setup。因此类似 telescope-fzf-native 这类替换默认 sorter的扩展正是在setup阶段完成对内部排序函数的覆写。2.2 扩展的安装与调用扩展装好后用户侧的使用方式有两种见 README.md-- Lua 方式加载并覆盖默认文件 sorter require(telescope).load_extension(fzy_native) 命令方式通过 :Telescope 调用扩展导出的 picker Telescope dap configurations 也可以直接以 Lua 调用 :lua require(telescope).extensions.dap.configurations()值得注意的细节是如果跳过显式load_extension扩展会被惰性加载但:Telescope的 Tab 补全不会立即可用。而在extensions {}配置块中传入的配置正是setup(ext_config, ...)收到的第一个参数由extensions.set_config写入_config表。三、提交规范Issue 先行与 PR 模板3.1 新特性先开 IssueCONTRIBUTING.md 建议提交新特性前最好先创建 issue 以评估社区兴趣与可行性it is a good idea to create an issue first to gauge interest and feasibility。这与仓库的 .github/ISSUE_TEMPLATE/ 模板体系相互配套.github/ISSUE_TEMPLATE/bug_report.yml结构化 Bug 报告表单强制填写 Description、nvim --version输出、操作系统版本、telescope 版本、:checkhealth telescope输出、复现步骤、期望/实际行为并内置一份可独立运行的 minimal config基于 lazy.nvim 自举隔离用户环境仅保留复现所需的依赖。.github/ISSUE_TEMPLATE/feature_request.md功能请求模板要求描述问题背景、期望的解决方案、替代方案及附加上下文。3.2 PR 模板与自查清单.github/PULL_REQUEST_TEMPLATE.md 要求每个 PR 说明改动摘要与修复的 issue 编号、变更类型Bug 修复 / 新特性 / 破坏性变更 / 需要文档更新、测试方式与复现步骤、环境信息。其 Checklist 与本仓库的工程规范直接相关代码风格遵循 stylua完成了自我 review在难理解处添加了注释对文档做了相应修改lua annotations——这一项与下文的 docgen 工作流直接呼应。四、文档即代码emmylua 注解与make docgen这是 CONTRIBUTING.md 中唯一以 ## 开头的独立章节也是该项目贡献流程中最具特色的部分The docs are generated from the code using emmylua annotations. To update them after making changes to the code, runmake docgen. A Check docs workflow in CI ensures that the documentation matches any change to the code and its annotations.即项目文档doc/telescope.txt等不是手写维护的而是从源码中的 emmylua 注解自动生成的。4.1 注解从何而来在核心入口 lua/telescope/init.lua 中可以直观看到这类注解---brief用于生成文档开篇简介包括一张纯文本绘制的 telescope 架构图---eval return require(telescope).__format_setup_keys()动态求值生成setup()的全部默认键文档---param opts table: Configuration opts. Keys: defaults, pickers, extensions声明函数参数类型。同理setup、load_extension、register_extension等公开 API 均通过注解在:help中呈现。4.2 docgen 如何工作make docgen由根目录 Makefile 定义.deps/docgen.nvim: git clone --depth 1 --branch v1.1.0 https://github.com/jamestrew/docgen.nvim $ docgen: .deps/docgen.nvim nvim -l scripts/gendocs.lua它先克隆固定版本v1.1.0的 docgen.nvim 到.deps/再以无头模式执行 scripts/gendocs.lua。后者将项目根、plenary 与 docgen.nvim 加入 rtp然后调用require(docgen).run{...}其files表一一映射了源码模块与文档章节标题例如lua/telescope/init.lua→INTRODUCTIONtagtelescope.nvimlua/telescope/command.lua、lua/telescope/builtin/init.lua、lua/telescope/themes.lua、lua/telescope/mappings.lua→ 对应帮助章节lua/telescope/pickers/layout.lua→LAYOUTtagtelescope.layoutlua/telescope/pickers/layout_strategies.lua→LAYOUT_STRATEGIESlua/telescope/config/resolve.lua→RESOLVE以及make_entry.lua、entry_display.lua、utils.lua、actions/系列、previewers/init.lua等也就是说凡是被列入files表的模块其公开函数的 emmylua 注解都会进入:help telescope.*。贡献者新增或修改 API 时必须同步更新注解并重新运行make docgen才能让doc/telescope.txt反映真实代码。4.3 CI 如何强制文档与代码同步.github/workflows/docgen.yml 实现了名为 Check docs 的 CI 检查在 ubuntu-latest 上安装最新 stable Neovim、克隆 plenary 并将当前仓库软链接到 packpath然后执行make docgen与git diff --exit-code。任何代码或注解变更若未同步重新生成文档diff 就会非空CI 直接失败。这正是 CONTRIBUTING.md 所说 ensures that the documentation matches any change to the code and its annotations 的落地实现也是 PR 模板中已对文档lua annotations做出相应修改勾选项被强制的原因。五、质量保障测试与 lint除了文档校验贡献者的改动还会经过完整的测试与静态检查相关入口同样集中在根目录 Makefiletest: nvim --headless --noplugin -u scripts/minimal_init.vim -c PlenaryBustedDirectory lua/tests/automated/ { minimal_init ./scripts/minimal_init.vim } lint: luacheck lua/telescopemake test以无头模式启动 Neovim加载 scripts/minimal_init.vim用 plenary 的 Busted 目录运行 lua/tests/automated/ 下的全部自动化测试覆盖 find_files、live_grep、action、sorter、layout_strategies、entry_display、resolver、scroller 等模块测试实现见 lua/tests/helpers.lua。make lint使用 luacheck 对 lua/telescope 全目录做静态检查。.github/workflows/ci.yml 将make test部署到 ubuntu / macos / windows 三个平台并在 nightly 与 stable 两个 Neovim 版本上各跑一遍同时安装 ripgrep 以满足 live_grep 类测试的外部依赖。因此贡献者提交前最好先在本地跑通make test与make lint。六、贡献者行动清单综合 CONTRIBUTING.md、Makefile、.github/ 下的模板与工作流一个符合 telescope.nvim 社区预期的贡献流程可以总结为判断归属新 picker 需求优先打包为扩展结构见 developers.md 的 Bundling as extensionBug 修复、文档改进、非 picker 特性欢迎直接进入核心仓库。先讨论后动手新特性先开 issue参考 .github/ISSUE_TEMPLATE/feature_request.md评估可行性Bug 报告按 .github/ISSUE_TEMPLATE/bug_report.yml 提供最小复现配置。代码与注解同行修改公开 API 时同步更新对应 Lua 文件的 emmylua 注解并运行make docgen重新生成 doc/telescope.txt 等帮助文档。本地验证运行make test与make lint确保改动通过自动化测试与静态检查PR 中按 .github/PULL_REQUEST_TEMPLATE.md 填写变更类型、测试方式与 checklist。这套流程的核心思想是以文档一致性作为代码合入的门禁通过 emmylua 注解 docgen CI diff 检查让:help telescope永远与源码保持同步同时用保守的准入策略把核心仓库的长期维护面控制住把更丰富的 picker 生态留给扩展体系去承载。【免费下载链接】telescope.nvimFind, Filter, Preview, Pick. All lua, all the time.项目地址: https://gitcode.com/GitHub_Trending/te/telescope.nvim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考