美化你的 GitHub 仓库

美化你的 GitHub 仓库

无论你是否喜欢，GitHub 已经成为托管代码的主要提供商。你或你的公司可能正在使用 GitHub。在本文中，我想重点介绍一些可以美化你的 GitHub 仓库的文件。

自述文件

我希望现在大家都熟悉了 READMES。如果将 README 文件放在仓库的根目录下，GitHub 会将其内容显示在仓库的主页上。

然而，这里有一些您可能不知道的提示。

README 可能采用不同的格式：

请注意，HTML 不起作用：GitHub 显示原始 HTML 代码，而不是“渲染”的 HTML。

此外，您还可以为组织设置 README 文件。首先，您需要创建一个与组织同名的仓库。然后，在该/.github/profile/目录下创建所需的 README 文件。例如，请查看此博客中显示自定义页面的组织。

有关更多详细信息，请查看文档。

执照

如果你希望人们使用你的代码，你应该告诉他们使用条款。这正是代码许可的目的。传统上，大多数软件包的根目录下都有一个LICENSE（或）文件。GitHub 也采用了这种做法。LICENSE.txt

你可以选择任何你想要的许可证，但 GitHub UI对开源许可证提供了很好的帮助。前往“添加文件”>“创建新文件”。如果你为新文件命名LICENSE，将会弹出一个新按钮：选择许可证模板。点击它后，GitHub 会提供以下选项：

• Apache 许可证 2.0
• GNU 通用公共许可证 v3.0
• MIT 许可证
• BSD 2 条款“简化”许可证
• BSD 3 条款“新”或“修订”许可证
• Boost 软件许可证 1.0
• Creative Commons Zero v1.0 通用
• Eclipse 公共许可证 2.0
• GNU Affero 通用公共许可证 v3.0
• GNU 通用公共许可证 v2.0
• GNU 宽通用公共许可证 v2.1
• Mozilla 公共许可证 2.0
• 无证

您可以选择其中一个来检查其内容。GitHub 会显示其权限、限制和条件：

现在您可以审核并提交。此时，您面临三个选择：

1. 取消更改将取消所有内容
2. 选择许可证模板返回许可证选择
3. 提交新文件...将新选择的许可证提交到存储库

添加许可证后，GitHub 会将其显示在存储库页面的右侧。

有关更多详细信息，请查看文档。

代码所有者

GitHub 会自动将配置的代码所有者添加到拉取请求中。您可以在一个CODEOWNERS文件中定义它们，其格式类似于.gitignore。

以下是 GitHub 处理该问题方式的简要总结：

• 您可以CODEOWNERS在根目录或.github子文件夹中设置
• 每个分支可以有不同的文件

• 通用配置行由模式和所有者组成：
  

  *.txt    @nfrankel
  

  @nfrankel拥有所有txt文件

• 与 一样.gitignore，配置将按顺序应用。底部的行会覆盖顶部的行：
  

           @johndoe
  docs     @nfrankel
  

  @johndoe拥有一切，但@nfrankel拥有docs文件夹

• 您可以设置多个所有者：
  

           @johndoe @nfrankel
  

• 所有者可以是个人，也可以是团队。要定义团队，请使用组织名称加上团队名称作为后缀：
  

           @ajavageek/developers
  

• 您无法审核自己发起的拉取请求！如果您是发起拉取请求来测试配置的人，GitHub 会跳过您（参见StackOverflow）。

GitHub 会跳过无效的配置行。要验证，您可以使用 UI：

安全

项目希望人们报告安全问题。但沟通渠道必须私密，以免黑客在问题得到缓解、修复或两者兼而有之之前发现。为此，GitHub 提供了一个自定义的 SECURITY 文件：

• 与 README 文件一样，它可以采用不同的格式：

  文件名	格式
  SECURITY	原始文本
  SECURITY.txt
  SECURITY.md	（GitHub 风格）Markdown
  README.adoc	阿西医生

• 与 CODEOWNERS 文件一样，您可以将其放在 repo 的根目录或.github子文件夹中

设置 SECURITY 文件最简单的方法是通过 UI。转到“安全”选项卡，然后单击“设置安全策略”按钮。在新窗口中单击“开始设置”按钮。

GitHub 提供了默认的 Markdown 模板，当然你也可以选择更改格式和内容。重点是告诉用户如何报告安全漏洞。

新创建的文件将显示在“安全”>“查看安全策略”中。以下是Asciidoctor 格式的示例。

引用

如果你的项目很优秀，其他项目很可能会使用它。你的项目可能会在学术著作中被引用，如果项目本身具有学术性质，引用次数就更高。CITATION 文件可以帮助你回答以下问题：

• 该软件的名称是什么？
• 我应该使用什么标签来唯一地标识我所使用的软件的版本？
• 哪些人适合被引用为作者？

标准的 CITATION 格式是GitHub 提出的Citation File Format：

CITATION.cff文件是纯文本文件，包含人机可读的软件（和数据集）引用信息。代码开发人员可以将它们添加到他们的代码库中，以便其他人了解如何正确引用他们的软件。

您不仅可以选择如何格式化引用，还可以引用其他来源，例如相关的学术文章。

再次强调，GitHub 的 UI 可以帮助用户创建CITATION.cff文件。创建文件后，它会提示你添加一个示例，你可以根据需要进行编辑。

cff-version: 1.2.0
title: Beautify GitHub sample repository
message: If you really want to cite this repository, here's how you should cite it.
type: software
authors:
  - given-names: Nicolas
    family-names: Fränkel
repository-code: 'https://github.com/ajavageek/beautifygithub'
license: Unlicense

添加文件后，右侧边栏会出现一个新的“引用此存储库”链接。点击后，您可以选择要复制的格式：APA 或 BibTeX。

赞助

最后，同样重要的是，让我们看看如何配置赞助。如果您通过开源项目为第三方提供价值，那么让他们奖励您是合理的。但请注意，您不应该指望它，否则您可能会大吃一惊。

FUNDING.ymlGitHub 允许通过仓库中的专用界面显示赞助选项.github。用户界面再次提供了帮助。前往“设置”，然后点击“设置赞助商”按钮。它会打开一个常用窗口，用于创建一个包含模板的新文件。以下是我修改后的操作：

github:
  - nfrankel
custom:
  - https://paypal.me/nicofrankel

预览选项卡验证您的输入。

在这种情况下，验证失败，因为用户nfrankel（我）没有注册 GitHub 赞助商计划。

该 repo 主页的右侧边栏上出现了一个新的“赞助此项目”部分。

您需要在“设置”中勾选“赞助”复选框才能显示它。这样，您就可以在 repo 中准备好所有内容，并在准备就绪时激活它。

结论

GitHub 提供了多种方法来提升你的仓库的显示效果和可用性。任何你想与他人共享的仓库都必须提供 LICENSE 和 README 文件。除此之外，你还应该提供本文列出的其他美化方法。

这篇文章的完整源代码可以在 GitHub 上找到：

进一步来说：

• 自定义你的存储库
• 向您的存储库添加安全策略
• 引文文件格式（CFF）
• 关于 CITATION 文件
• GitHub 特殊文件和路径

最初于2022 年4 月 17 日^发表于A Java Geek