GitHub 存储库最佳实践

概述

作为一名 DevOps 工程师，管理GitHub 代码库与代码库本身一样重要。一个维护良好的GitHub代码库为高效的协作、代码质量和精简的工作流程奠定了基础。在本博客中，我们将讨论并总结我提出的 10 条有效管理GitHub 代码库的最佳实践技巧。

提示 1：使用清晰的存储库命名约定

GitHub 中清晰的存储库命名约定至关重要，因为它有助于组织和清晰度，这在协作环境中至关重要。

清晰的存储库命名约定可以更轻松地：

• 一眼就能识别存储库的目的和内容。
• 更有效地搜索和检索存储库。
• 在团队和项目中采用标准化方法。
• 通过预测存储库的结构和命名，实现自动化，从而提高工作效率。例如，CI/CD 工作流可以根据命名约定部署版本。

让我们看一些例子：

• 按项目或团队添加前缀：如果您的组织有多个项目或团队，则可以从标识它们的前缀开始，例如teamalpha_authentication_service或teambravo_data_pipeline。
• 使用描述性名称：存储库应该具有描述性和特定的名称，以告诉您里面有什么，例如customer_support_ticketing_system或machine_learning_model_trainer。
• 包含技术堆栈image_processor_python：在名称中包含主要技术堆栈（例如或frontend_react_app）可能很有用，特别是对于微服务架构而言。
• 版本控制或状态标签：如果您维护工具或库的不同版本，或者存储库包含处于特定开发阶段的某些内容，请在名称中指明这一点，例如payment_gateway_v2或inventory_management_deprecated。
• 避免使用特殊字符：坚持使用简单的字母数字字符和连字符/下划线以保持 URL 兼容性并避免混淆，例如invoice-generator或invoice_generator。
• 用例：有时指示存储库是库、服务、演示还是文档可能会有所帮助authentication_lib，例如payment_api_service，，，demo_inventory_app。api_documentation

通过遵循清晰标准化的存储库命名约定，您可以确保团队中的每个人都能更高效地浏览存储库，在深入研究每个存储库之前预测其性质和内容，并在直观的结构的指导下协同工作。最终，这将带来更好的协作、节省时间并减少错误，使团队能够专注于构建和部署，而不会陷入组织混乱的泥潭。

技巧 2：根据主题对存储库进行分类

GitHub 允许您使用主题对仓库进行分类。主题是可以添加到仓库的标签，用于帮助分类和发现项目。主题是根据仓库的用途、技术栈或任何其他相关标准对其进行组织和分组的绝佳方式。

您可以通过导航到仓库的“关于”设置来编辑仓库详情，然后选择“主题”选项卡，将主题添加到仓库。然后，您可以添加与仓库相关的主题。

将主题添加到存储库很有用，原因如下：

• 可发现性：让其他人更容易找到您的仓库。当有人搜索某个主题时，包含该主题的仓库将包含在搜索结果中。
• 组织：帮助您组织存储库。您可以根据存储库的用途、技术栈或任何其他相关标准对其进行分组。
• 社区：帮助您与对相同主题感兴趣的人建立联系。当有人查看包含某个主题的仓库时，他们可以看到包含相同主题的其他仓库。
• 洞察：提供贵公司常用技术和工具的洞察。您可以使用这些信息来识别趋势，并就所使用的技术和工具做出明智的决策。
• 标准化：帮助您标准化存储库的分类方式。您可以在所有存储库中使用相同的主题，以确保一致性。

向仓库添加主题时，务必选择相关且有意义的主题。您应该选择能够准确描述仓库用途、技术栈或其他相关标准的主题。

您可以从GitHub repo 主题文档中获取有关主题的更多信息以及如何有效地使用它们。

技巧 3：使用 README.md 来记录存储库

一个文档齐全的仓库对于开发者、贡献者和维护者来说就像一座宝库。README.md访客进入你的仓库时，首先看到的就是该文件。它非常适合快速概述仓库、其用途以及如何开始使用它。它可能包含以下实用信息：

• 项目描述
• 设置说明
• 使用示例
• 贡献指南
• 许可证信息

一份编写良好的README.md文件可以帮助您：

• 吸引贡献者：吸引贡献者参与您的项目。它为他们提供了解项目和开始项目所需的信息。
• 入职培训：帮助新团队成员快速熟悉项目。它为他们提供理解项目并开始为项目做出贡献所需的信息。
• 文档：作为项目的文档。它为用户提供使用项目所需的信息。
• 推广：帮助推广您的项目。它为潜在用户提供了解项目所需的信息，并帮助他们决定是否使用项目。
• 标准化：帮助您标准化项目记录方式。它为您的项目记录提供了一致的结构。

编写README.md文件时，务必保持简洁明了。您应该将最重要的信息放在文件顶部，并在必要时提供指向更详细信息的链接。您还应使用格式使文件易于阅读，并在适当的位置添加图片和其他媒体文件。

README.md您可以在GitHub repo readme 文档中获得有关如何编写良好文件的更多信息。

技巧 4：采用一致的分支策略

一致的分支策略对于有效的协作和代码管理至关重要。它为代码变更的管理及其与代码库的集成提供了清晰的结构。它还有助于维护代码库的整洁稳定，并降低冲突和错误的风险。

您可以采用多种分支策略，例如：

• Gitflow：一种流行的分支策略，使用两个主分支master和develop，以及各种支持分支来帮助并行开发和发布管理。
• 功能分支feature：一种在专用分支中开发每个任务，然后main在完成后合并到分支的策略。
• 基于主干的开发：一种将所有更改直接发送到main分支的策略，并使用功能切换或其他技术来管理不完整的功能。
• GitHub Flow：一种轻量级分支策略，使用单个main分支，并为每个新功能或错误修复创建功能分支。
• GitLab Flow：一种类似于 GitHub Flow 的策略，但增加了环境和发布分支来管理发布过程。
• 发布分支：一种release从分支创建分支main以准备新发布的策略，然后在发布完成后合并回主分支。
• 环境分支：使用分支来管理不同环境的策略，例如development、staging和production。

选择分支策略时，务必考虑团队和项目的需求。您应该选择简单、灵活、可扩展且支持团队工作方式的策略。您还应该记录分支策略，并确保团队中的每个人都了解其工作原理并始终如一地遵循它。

您可以通过查看官方文档来获取有关分支和如何使用分支的更多信息：GitHub repo 分支文档。

技巧 5：使用分支保护规则保护你的存储库

分支保护规则是 GitHub 的一项强大功能，允许您对分支强制执行某些限制和要求。它们可以帮助您维护干净稳定的代码库，并帮助您避免错误，从而提高代码的质量和安全性。

举几个例子，您可以使用分支保护规则来：

• 要求拉取请求审核：要求一定数量的审核者批准拉取请求后才能合并。
• 需要状态检查：要求在合并拉取请求之前通过某些状态检查，例如 CI/CD 检查。
• 合并前要求对话解决：要求在合并拉取请求之前解决有关该请求的所有对话。
• 要求签名的提交：要求提交在合并之前必须经过验证的签名。
• 要求线性历史记录：要求拉取请求的提交历史记录是线性的，然后才能合并。
• 需要合并队列：要求使用合并队列合并拉取请求，例如 GitHub Actions 或第三方服务对合并队列中的拉取请求运行所需的检查。
• 要求部署在合并前成功：要求在合并拉取请求之前，必须成功部署到某些环境（例如生产环境）。

您可以在GitHub repo 分支保护文档中获取有关分支保护规则及其使用方法的更多信息。

使用分支保护规则时，务必在强制执行限制和要求与确保团队高效工作之间取得平衡。您应该考虑团队和项目的需求，并选择支持团队工作方式的规则。您还应该记录规则，并确保团队中的每个人都了解规则的运作方式并始终如一地遵守。

技巧 6：维护干净的提交历史

清晰的提交历史记录对于有效的协作和代码管理至关重要。它清晰地记录了代码库的变更，有助于维护代码库的整洁稳定。它还能让您更轻松地了解代码库的历史记录，并降低冲突和错误的风险。

您可以采用几种最佳实践来维护干净的提交历史记录，例如：

• 编写描述性的提交消息：编写清晰且描述性的提交消息，解释所做更改的目的和背景。
• 使用原子提交：进行小规模、集中提交，只包含单个逻辑更改。这样更容易理解代码库的历史记录，并降低冲突和错误的风险。
• 使用有意义的提交标题：使用有意义的提交标题来概括所做更改的目的。
• 使用一致的格式：对提交消息使用一致的格式，例如使用祈使语气并将第一行保持在 50 个字符或更少。
• 使用签名的提交：使用签名的提交来验证提交的真实性并防止篡改。

例如，好的提交消息如下所示：

git commit -m "Add user authentication mechanism to the inventory management system"

传达以下模糊的信息是不好的做法：

git commit -m "Fixed stuff"

在维护清晰的提交历史记录时，务必考虑团队和项目的需求。您应该选择简单、灵活、可扩展且支持团队工作方式的实践。您还应该记录这些实践，并确保团队中的每个人都了解其工作原理并始终如一地遵循它们。

技巧 7：利用 .gitignore

该.gitignore文件是一种简单有效的方法来管理您想要从版本控制中排除的文件和目录。它允许您指定与您想要忽略的文件和目录匹配的模式，并阻止它们被添加到存储库。

仅举几例，该.gitignore文件特别适用于：

• 忽略构建工件：忽略构建过程中生成的文件和目录，例如日志文件、临时文件和构建工件。
• 忽略敏感信息：忽略包含敏感信息的文件和目录，例如密码、API 密钥和配置文件。
• 忽略用户特定文件：忽略特定于单个用户的文件和目录，例如编辑器设置、本地配置和临时文件。
• 忽略大文件：忽略较大且对于版本控制不必要的文件和目录，例如媒体文件、二进制文件和档案。
• 忽略日志和缓存：忽略作为日志记录和缓存过程的一部分创建的文件和目录，例如日志文件、缓存文件和临时文件。
• 忽略测试文件：您可以.gitignore忽略作为测试过程的一部分创建的文件和目录，例如测试结果、测试日志和测试工件。

使用时.gitignore，务必考虑团队和项目的需求。您应该选择简单、灵活、可扩展且支持团队工作方式的模式。您还应该记录这些模式，并确保团队中的每个人都了解它们的工作原理并始终如一地遵循它们。

您可以在GitHub repo .gitignore 文档中获得更多信息.gitignore以及如何有效地使用它。

技巧 8：使用 GitHub Actions 进行 CI/CD

GitHub Actions 是 GitHub 的一项强大功能，可让您通过工作流程自动执行任务。它提供了一种灵活且可扩展的方式来构建、测试和部署代码，并帮助您维护干净稳定的代码库。

GitHub Actions 本身就是一个很大的话题，但仅涉及几个主题，您可以使用 GitHub Actions 来：

• 自动化构建过程：每当存储库发生更改时，都会自动构建代码。
• 自动化测试：每当存储库发生更改时，自动运行测试。
• 自动化部署流程：每当存储库发生更改时，都会自动部署代码。
• 自动发布：每当存储库发生更改时，都会自动创建发布。
• 自动化文档：每当存储库发生更改时，使用 GitHub Actions 自动生成文档。
• 自动化 IaC：自动化基础设施即代码 (IaC) 任务，例如配置、配置和部署基础设施。
• 自动化安全检查：自动化安全检查，例如漏洞扫描、依赖关系分析和代码分析。

这个列表还在继续，但重点是 GitHub Actions 是一个强大的工具，可以帮助您自动执行管理代码库所涉及的许多任务。

务必考虑团队和项目的需求。您应该选择简单、灵活、可扩展且能够支持团队工作方式的工作流程。您还应该记录工作流程，并确保团队中的每个人都了解其工作原理并始终如一地遵循这些工作流程。

您可以从官方GitHub Actions 文档中获取有关 GitHub Actions 的更多信息以及如何有效地使用它们。

技巧 9：利用问题跟踪和项目

GitHub 提供了强大的问题跟踪系统，可让您管理和跟踪问题、错误和功能请求。它还提供项目状态板，可让您管理和跟踪工作进度。

Github Projects还可以帮助您更有效地管理工作，并改善团队内部的协作和沟通。

问题跟踪和项目很有用，原因如下：

• 跟踪问题和错误：跟踪问题和错误，并管理修复它们的过程。
• 跟踪功能请求：跟踪功能请求，并管理实现它们的过程。
• 计划和确定工作优先顺序：计划和确定工作优先顺序，并管理完成工作的过程。
• 管理发布：管理发布，并通过里程碑跟踪工作进度。
• 协作和沟通：与您的团队协作和沟通，提高代码的质量和安全性。
• 标签：使用标签对问题进行分类，以便于管理和跟踪问题。（例如bug，，）。enhancementhelp wanted

您可以从官方GitHub 问题跟踪文档和GitHub 项目文档中获取有关问题跟踪和项目板的更多信息以及如何有效地使用它们。

技巧 10：利用 GitHub 安全功能

GitHub 提供了一系列安全功能，可帮助您提高代码库的安全性。这些功能可以帮助您识别和修复安全漏洞，并主动保护您的代码免受安全威胁和泄漏。

举几个例子，您可以使用 GitHub 安全功能来：

• 易受攻击的依赖项的安全警报：当您的存储库具有易受攻击的依赖项时获取警报。
• 代码和秘密扫描：扫描您的代码以查找安全漏洞、代码中存在的秘密以及编码错误。
• Dependabot 安全/依赖项更新：使用Github Dependabot自动将您的依赖项更新到最新的安全版本。
• 安全策略和建议：为您的存储库创建和管理安全策略和建议。
• 依赖关系洞察：洞察代码库的安全性/依赖关系，并使用依赖关系图确定需要改进的领域。

欲了解更多信息，并深入了解 GitHub 原生提供的一些安全功能和工具，我建议您查看本博客系列的早期博客文章：使用 GitHub 保护您的代码

结论

在本篇博客中，我们仅涉及几个主题，并讨论了一些有效管理 GitHub 仓库的最佳实践。想要了解更多有价值的信息，请点击此链接，获取关于如何设置项目以实现健康贡献的更多指南。

我希望你喜欢这篇文章并学到了一些新东西。❤️

作者

喜欢、分享、关注我：🐙 GitHub | 🐧 X/Twitter | 👾 LinkedIn

马塞尔·L跟随

微软 MVP DevOps + Azure 双认证 | DevOps 架构师 | 技术演讲者，专注于微软技术、Azure 中的 IaC 和自动化。在 GitHub 上找到我：https://github.com/Pwd9000-ML