vlambda博客
学习文章列表

README 文件

README文件，这是一种常见的自述文件。如果将它放在自己仓库的根目录中，GitHub会在该仓库的首页中显示其内容。

请注意不要使用HTML，它不会起作用。GitHub 会将HTML显示为原始代码，而不是“渲染”后的页面。

你也可以为自己的组织设置自述文件。如果已经创建过一个组织类型的存储库，在.github/profile下保存一个README文件即可，比如要给用户查看的文档结构图。

如果希望人们使用你的代码，你应该告诉他们可以在哪些开源条款下使用它。也正是这些许可能够保护你的代码。

传统上，大多数软件包的根目录下都有一个LICENSE（或LICENSE.txt）文件，GitHub 也采用了这种做法。

要创建开源相关许可证，GitHub UI为开发者提供了很好的帮助。转到添加文件->创建新文件。

比如创建新文件LICENCE，选择许可证模板，可以选择GitHub的以下选项：

• Apache License 2.0.

• GNU General Public License v3.0.

• MIT License.

• BSD 2-Clause "Simplified" License.

• BSD 3-Clause "New" or "Revised" License.

• Boost Software License 1.0.

• Creative Commons Zero v1.0 Universal.

• Eclipse Public License 2.0.

• GNU Affero General Public License v3.0.

• GNU General Public License v2.0.

• GNU Lesser General Public License v2.1.

• Mozilla Public License 2.0.

• The Unlicense.

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

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

代码所有者

GitHub会自动将仓库配置者添加到拉取请求中。开发者可以将所有者名单定义在CODEOWNERS的文件中中，它的格式有点像.gitignore文件。

GitHub 处理的规则总结如下：

1、可以将CODEOWNERS文件放在根目录或者.github子文件夹中；

2、每个分支可以有不同的CODEOOWNERS文件；

3、通用配置中的行，由模式和所有者组成：

*.txt    @nfrankel

这表示@nfrankel 拥有全部txt文件。

4、与.gitignore一样，配置是按顺序应用。底部一行会覆盖顶部行：

 @johndoe
docs @nfrankel

@johndoe拥有全部，但@nfrankel拥有docs文件夹。

我们可以设置多个所有者。类似如下：

         @johndoe @nfrankel

所有者可以是个人，也可以是团队/组织。如果是公司团队/组织，请使用有团队名称后缀的组织名称：

         @ajavageek/developers

注意：配置用户无法查看自己的拉取请求。

GitHub 默认会跳过不正确的配置行，如果想验证配置文件中的所有行都是正确的，可以使用GitHub UI 对文件书写进行校验。如下图所示：

安全

项目也希望使用者报告相关安全问题，但是通信和沟通渠道必须是私密的，这样黑客才不会在问题得到修复之前就知晓相关Bug。

GitHub 提供了一个自定义 SECURITY 文件：

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

设置 SECURITY 文件的最简单方法是通过GitHub UI。转到安全选项卡，然后单击设置安全策略按钮。

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

引用

如果你的项目很好，其他项目可能会使用它。该项目也可能在学术著作中被引用，如果它本身具有学术性质，则应该使用CITATION 文件，该文件包括如一下提示：

软件的名称是什么？

我应该使用唯一标识使用的软件版本？

哪些人应该被引用为作者？

CITATION 全称为 Citation File Format，由 GitHub 提出：

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

添加CITATION文件后，右侧栏中会出现一个新的Cite this repository链接。可以在单击时选择要复制的格式，如APA 或 BibTeX。

赞助

最后一个，但同样重要——让我们看看如何配置赞助配置文件。如果你通过开源项目向第三方提供价值，那么让他们鼓励你是非常有意义的。

GitHub 允许在存储库中加入FUNDING.yml中显示专用赞助选项，仍然可以借助GitHub UI提供帮助。转到设置并单击设置赞助商按钮。它打开新窗口并附加一个带有模板的新文件。

下面是修改后的代码例子：

github:  - nfrankelcustom: - https://paypal.me/nicofrankel

预览选项卡验证内容输入是否正确。

在以上情况下，验证会失败，因为用户nfrankel 还没有注册 GitHub 赞助商计划。

“赞助这个项目”部分出现在主页的右侧边栏上。你需要选中“设置”中的“赞助”复选框才能显示。因此可以准备好 repo 中的所有内容后再激活该选项。

结论

GitHub 提供了多种方法来改善存储库的展示和可用性。对于你想要与他人共享的任何存储库，许可证和自述文件都应该是必须且强制性的。除此之外，开发者还可以提供本文中列出的其它美化效果。

本文的完整源代码可以在GitHub上找到。

https://github.com/ajavageek/beautifygithub

编辑：场长

来源：A Java Geek

相关阅读：