贡献与开发

目的与范围

本指南旨在帮助所有经验水平的开发者有效贡献 bat。它解释了贡献工作流程、开发设置、测试程序以及提交代码更改的最佳实践。文档的结构旨在遵循从初始设置到 PR 提交的典型贡献生命周期。

开始贡献

bat 项目欢迎各种贡献，从错误修复和文档改进到新功能和语法定义。在开始贡献之前，了解整体流程会很有帮助。

贡献工作流程概述

来源： CONTRIBUTING.md1-58

设置开发环境

在为 bat 贡献代码之前，您需要设置开发环境。

Fork 并克隆仓库
安装 Rust 开发工具 (如果尚未安装)
安装所需依赖
构建项目

开发设置流程

README 在“开发”部分包含有关开发设置的详细信息。基本工作流程涉及标准的 Rust 开发工具和实践。

来源： CONTRIBUTING.md47-50

了解贡献指南

在提交您的贡献之前，了解项目的指南以确保您的更改被接受非常重要。

添加变更日志条目

维护变更日志对于跟踪更改和促进发布至关重要。对于大多数类型的更改，您都需要为 CHANGELOG.md 文件添加条目。

何时添加变更日志条目

需要变更日志条目	不需要变更日志条目
`bat` 行为更改	文档更新
语法映射更改	拼写错误修复
语法定义更改
主题更改
构建系统/CI 更改

变更日志条目格式

条目必须遵循此格式

- Short description of what has been changed, see #123 (@username)

#123 是您的 PR 编号，@username 是您的 GitHub 用户名。

变更日志验证

该项目使用 GitHub Actions 工作流程，该工作流程会自动验证每个拉取请求是否具有正确的变更日志条目。此工作流程检查

已向 CHANGELOG.md 添加了一行
该行包含 PR 编号
该行包含 PR 提交者的 GitHub 用户名

来源： CONTRIBUTING.md7-44 .github/workflows/require-changelog-for-PRs.yml1-34

贡献类型

Bug 修复

修复错误时，重要的是

查明根本原因
提供全面的解决方案
添加回归测试以防止错误再次发生
更新变更日志

错误修复工作流程

提交错误报告时，请使用错误报告模板，其中要求

重现步骤
预期行为与实际行为
安装方法
诊断信息 (bat --diagnostic)

来源： .github/ISSUE_TEMPLATE/bug_report.md1-65 CONTRIBUTING.md72-91

添加新功能

对于新功能

提交功能请求以首先讨论细节
实现功能讨论后
添加测试以实现新功能
更新文档
添加变更日志条目

该项目强烈鼓励在实现新功能之前提交功能请求 issue，以确保与项目目标一致并讨论实现细节。

来源： CONTRIBUTING.md53-57 .github/ISSUE_TEMPLATE/feature_request.md1-10

添加新的语法或主题

bat 支持添加新的语法和主题。此过程与其他贡献略有不同。

语法/主题贡献流程

新语法的合格标准

在提交语法以包含在 bat 中之前

确保它符合标准（例如，在 packagecontrol.io 上下载量超过 10,000 次）
检查是否可以本地添加

项目文档解释说，用户可以本地添加语法，而无需将其包含在主存储库中。对于不太常见的语法，这是首选方法。

来源： CONTRIBUTING.md60-69 .github/ISSUE_TEMPLATE/syntax_request.md1-30

详细的贡献工作流程

端到端贡献流程

此图说明了为 bat 贡献的典型工作流程。该过程从 fork 存储库开始，在审查后合并您的更改。

代码到项目映射

以下图表将贡献活动映射到存储库中的实际代码结构

来源： CONTRIBUTING.md1-91

测试您的更改

测试是贡献过程的关键部分。bat 使用不同类型的测试来确保代码质量。

回归测试

强烈鼓励所有贡献都进行回归测试。它们

确保您的贡献在未来不会失效
通过澄清预期行为使代码审查更容易

测试类型和执行流程

集成测试

对于功能性更改，请在 tests/integration_tests.rs 中添加测试。这些测试会调用 bat 二进制文件并断言 stdout/stderr。

集成测试模式示例

语法和主题测试

对于语法高亮和主题更改，请按照资产文档中的说明添加适当的测试。该项目使用快照测试系统来验证语法高亮行为。

来源： CONTRIBUTING.md72-91

贡献者存储库结构

以下图表说明了贡献过程如何映射到存储库中的实际代码结构

来源： CONTRIBUTING.md1-91 .github/workflows/require-changelog-for-PRs.yml1-34

沟通渠道

在为 bat 做贡献时，您可以使用各种沟通渠道

渠道	目的	模板
GitHub Issues	错误报告、功能请求	错误报告、功能请求模板
GitHub Discussions	问题、想法、支持	问题模板
Pull Requests	代码贡献	具有变更日志验证的 PR 模板

该项目鼓励使用 GitHub Discussions 来讨论 bat 的用法或开发问题。

来源： .github/ISSUE_TEMPLATE/question.md1-12

提交指南和最佳实践

拉取请求清单

在提交您的 PR 之前，请确保

您的代码遵循项目的样式指南
所有测试均通过
您已为新功能添加了适当的测试
您已更新变更日志
您的 PR 对更改有清晰的描述

代码风格

遵循 Rust 标准格式指南。在提交 PR 之前运行 cargo fmt 以确保格式一致。该项目使用标准的 Rust 代码风格并通过 CI 检查强制执行。

文档

添加新功能时，请更新相关文档以反映您的更改。这包括

代码注释
如有可能，更新 README
重要功能 Wiki 文档

贡献组件

以下图表将不同类型的贡献映射到代码库中相应的组件

代码组件映射

核心系统组件

此图显示了不同贡献区域与相应的代码文件或目录之间的关系，这些文件或目录需要进行修改。