模板标准和最佳实践

目的与范围

本文档概述了为 GitHub gitignore 仓库创建高质量 .gitignore 模板的标准和最佳实践。它提供了有关如何制作优秀模板、如何构建模板内容以及如何为仓库做出贡献的指南。有关如何为仓库做出贡献的常规信息，请参阅 Contributing to Gitignore。

什么样的模板是好的

高质量的 gitignore 模板应提供清晰、简洁的规则，以帮助仓库有效地处理特定的编程语言、框架、工具或环境。下图说明了优秀模板的关键特征

来源： README.md37-61

模板分类和组织

gitignore 仓库将模板分为三个主要类别，以保持结构并帮助用户找到合适的模板。了解这种组织方式对于创建新模板至关重要。

根模板：适用于广泛使用的通用编程语言和技术
全局模板：适用于编辑器、工具和操作系统（位于 /Global 目录）
社区模板：适用于专业或版本特定的模板（位于 /community 目录）

来源： README.md19-35 Global/README.md1-11

模板内容指南

在创建或修改模板时，请遵循以下内容指南，以确保它们对社区有用

指南	描述	示例
关注具体性	模板应针对特定语言、框架或工具	Python.gitignore 仅关注 Python 特定的模式
提供基本规则	包含通用生成文件、构建产物和日志的规则	`*.log`, `build/`, `dist/`
提供文档链接	尽可能引用官方文档	链接到解释生成文件的语言文档
添加描述性注释	用清晰的注释解释不明显的规则	`# 运行时生成的缓存文件`
避免个人偏好	规则应普遍适用，而非用户特定	不要在语言模板中包含特定于编辑器的文件
保持简洁	模板应专注，不应过于宽泛	避免列出所有可能生成的文件

来源： README.md37-61 CONTRIBUTING.md3-39

模板结构和格式

模板的结构和格式对其可用性至关重要。请遵循以下格式指南

头部信息

每个模板都应以提供上下文的头部开始

# gitignore template for [technology name]
# website: [link to official website]
#
# Recommended: [references to complementary templates if needed]

分组和组织

将相关规则分组，并使用注释分隔部分

# Build artifacts
build/
dist/
*.exe
*.dll

# Logs and databases
*.log
*.sql
*.sqlite

注释样式

使用清晰、简洁的注释来解释规则的用途

# Ignore configuration files that may contain sensitive information
config.json
.env

来源： community/Alteryx.gitignore1-44 Global/SynopsysVCS.gitignore1-37

处理版本特定的模板

对于版本之间差异很大的技术，请遵循以下指南

根目录下的模板应适用于当前支持的版本
根目录模板的文件名不应包含版本（例如，“evergreen”）
以前的版本应放置在 community/ 目录中
以前的版本应在文件名中包含版本以示清晰

来源： README.md92-106

创建专业模板

对于专业性强或非主流技术，请遵循以下指南

将模板放在 community/ 目录下的相应文件夹中
使规则特定于框架或工具
在头部注释中引用任何其他需要的模板
包含文档链接并解释模板的用途

专业模板的示例结构

# gitignore template for [specialized technology]
# website: [link to official website]
#
# Recommended: [related templates, e.g., VisualStudio.gitignore]

# [Section describing specific rule category]
[specific patterns for this technology]

来源： README.md108-135

贡献流程

在贡献新模板或更新现有模板时，请遵循此工作流程

提交拉取请求时

提供应用程序或项目的首页链接
包含支持更改的文档链接
解释为什么更改是必要的
考虑更改的范围
每次仅修改一个模板
确保模板遵循结构和格式指南

来源： README.md137-147 .github/PULL_REQUEST_TEMPLATE.md1-24

最佳实践清单

使用此清单确保您的模板符合质量标准

标准	要问的问题
范围	模板是否专注于特定的语言、框架或工具？
内容	是否包含常见的生成文件、构建产物和日志？
文档	是否提供了文档链接？是否解释了不明显的规则？
结构	模板是否逻辑组织，并带有适当的注释？
重复性	是否避免重复全局模式？
版本控制	如果是版本特定的，是否已正确标记和放置？
格式化	是否遵循标准的模板格式？
适用性	这些模式是否适用于该技术的所有用户，而不仅仅是个人偏好？

来源： README.md37-61 CONTRIBUTING.md3-39

常见错误及规避方法

包含用户特定文件：个人 IDE 配置属于全局模板
过于宽泛或过于具体：模板应平衡覆盖范围和重点
缺乏上下文：注释应解释不明显规则的用途
混合关注点：保持语言特定模式和工具特定模式的分离
过时的规则：确保模式与技术的当前版本相关
缺少重要模式：彻底研究以涵盖常见用例
格式不一致：遵循既定的格式以提高可读性

来源： README.md37-61 CONTRIBUTING.md3-39

结论

创建高质量的 gitignore 模板有助于用户通过排除不必要的文件来维护干净的存储库。通过遵循这些标准和最佳实践，您可以为使用您的模板所针对的特定技术的用户提高版本控制的效率。请记住，模板应该是专注的、有良好文档的，并且普遍适用的，以便提供最大的价值给社区。

最终目标是策划一个最常见和最有用的模板集合，而不是涵盖所有可能的项目。模板应帮助用户快速入门，并为他们特定的开发环境提供有意义的规则。

来源： README.md56-60 CONTRIBUTING.md36-39

模板标准和最佳实践

目的与范围

什么样的模板是好的

模板分类和组织

模板内容指南

模板结构和格式

头部信息

分组和组织

注释样式

处理版本特定的模板

创建专业模板

贡献流程

最佳实践清单

常见错误及规避方法

结论

本页内容