vlambda博客
学习文章列表

美化GitHub存储库的6种方法

美化GitHub存储库的6种方法


README 文件


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


文件名 格式
README 原始文本
README.txt
README.md (GitHub 风格)Markdown
README.adoc Asciidoctor


请注意不要使用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存储库的6种方法


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



美化GitHub存储库的6种方法


代码所有者


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 对文件书写进行校验。如下图所示:


美化GitHub存储库的6种方法


安全


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


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


文件名 格式
SECURITY 原始文本
SECURITY.txt
SECURITY.md (GitHub 风格)Markdown
README.adoc Asciidoctor


与 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


相关阅读: