【GitHub】记一次给 docusaurus 官方提交 pull request 的过程

发布时间:2023-12-02 11:30

\"CSDN开发云\"

文章目录

    • 一、缘起
    • 二、准备工作
      • 2. 语义化的提交信息 Semantic Commit Messages
      • 3. 测试计划
      • 4. CLA
    • 三、实操
    • 四、自动化测试 — 图片尺寸不符合规范
    • 五、合并成功
    • 六、总结

一、缘起

最近这段时间,我在做自己的静态网站,备选参考可以看我这个文章 https://coderfix.blog.csdn.net/article/details/125108431 ,基于各种考虑,我选择了基于 react 的 docusaurus 。

\"【GitHub】记一次给

当我通过他们的官网查询配置的时候,我看到官方有个showcase的板块,也就是站点展示。站点展示内我看到了一些个人网站也在里面。

那么,我能不能也把自己的网站提交上去呢?

二、准备工作

站点上来看,官方还是很愿意开发者把自己的网站贴在上面的,所以在 Showcase 页面显著位置就有引导按钮,帮助我查看提交步骤。

\"【GitHub】记一次给

通过这个链接,我点击进去之后到达的是 docusaurus 的 Github Repo 的页面,地址是https://github.com/facebook/docusaurus/edit/main/website/src/data/users.tsx,我可以看到页面上的站点数据都在这里,格式如下:

  {
    title: \'Blog Matheus Brunelli\',
    description:
      \'Desenvolvimento de software, carreira, dicas de livros e muito JavaScript!\',
    preview: require(\'./showcase/blogmatheusbrunelli.png\'),
    website: \'https://mrbrunelli.github.io/blog/\',
    source: \'https://github.com/mrbrunelli/blog\',
    tags: [\'opensource\', \'personal\'],
  },

那下一步的操作显而易见,我只需要提交自己的网站并合并即可。即,给开源项目提交一次 pull request

###1. 如何做一次标准的 pull request

俗话说得好,When in Rome do as the Romans do。对一个成熟的项目,我们先找到项目根目录的CONTRIBUTING.md,这个文件里会有详细的说明。

如果你是纯新手,先看看这个视频,https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github

以下是提交的步骤:

  1. 尽量保持短小的提交,代码量不要超过300行。
  2. 提交信息必须遵守规范
  3. 通过测试计划
  4. CLA

300行代码不解释,我们下面记录下其他的部分。

2. 语义化的提交信息 Semantic Commit Messages

提交格式 : ():

type 对应格式有:

  • feat :面向最终用户的接口或者行为
  • fix :面向最终用户的问题修复
  • docs :在仓库中更改网站或其他 Markdown 文档
  • refactor :对生产环境代码没有实质性改变
  • test :添加缺失的测试,重构测试; 没有生产代码更改
  • chore :升级依赖项,发布新版本,定期性质的维护工作
  • misc :不改变生产代码,但是也不属于test 和 chore 的工作

我要做的在Showcase上添加自己的网站,属于docs。

在项目已有的 pull request 中,我们可以看到,提交信息非常规范。

\"【GitHub】记一次给

3. 测试计划

目前项目已经做个集成测试,但是如果有重大变更,需要我们先做好本地测试。

由于我涉及到的代码属于文档类型,测试这部分暂且不表,后续有需要再开文章展开说明。

4. CLA

docusaurus 是 facebook 旗下的项目,那么,我们想要提交代码,就需要遵守对方的贡献者许可协议 (CLA)。

没有注册的话,我们需要先注册。

\"【GitHub】记一次给

填写信息之后通过Github授权。

\"【GitHub】记一次给

完成。

\"【GitHub】记一次给

三、实操

首先是 fork 到自己仓库,然后是 clone 到本地。

yarn install
yarn run start:website

修改的文件比较少,一个是website/src/data/users.tsx,另一个是在website/src/data/showcase中添加预览图片。

本地运行的效果如下。

\"【GitHub】记一次给

接下来就是提交信息咯,对于代码提交信息来说,规范没有那么严格。

\"【GitHub】记一次给

下面就是请求合并部分了,根据上面我们提到的文档,那么标题应为

docs: add Metalyoung to showcase

至于正文的部分,我在提交的时候,模板是会被填充到内容里面的,我要做的是填空即可。

\"【GitHub】记一次给

提交之后,我的提交合并地址为 https://github.com/facebook/docusaurus/pull/7597

然后就是耐心地等待。

\"image-20220611140258839\"

四、自动化测试 — 图片尺寸不符合规范

在我提交之后,仓库的 GitHub Action会自动进行各种测试。

\"【GitHub】记一次给

然后我发现自己的图片尺寸不对,被脚本识别出来了。

\"【GitHub】记一次给

然后,更新图片,继续提交。

\"【GitHub】记一次给

经过了一些时间的等待,自动测试都通过了,我的pull request 在列表上也出现了对号。

并且在写本文的之前,有个主要贡献者已经为我的pr添加了tag ,这说明我的 pr 已经被看到。

\"image-20220611190708411\"

还有一点,每行代码限制不要超过80,建议换行,或者使用格式化工具对代码进行格式化。

又经过了一段时间等待,所有的自动化测试都完成了。

\"【GitHub】记一次给

五、合并成功

再次经过了一段时间,我的pr被合并了~

\"【GitHub】记一次给

\"【GitHub】记一次给

当我们完成一次pr之后,可以选择删除fork的仓库。

\"image-20220611232118045\"

删除仓库的操作和其他没有区别。

\"【GitHub】记一次给

六、总结

目前,你在 https://docusaurus.io/ 官网的 showcase 上,已经可以看到我的个人网站链接了。

\"【GitHub】记一次给

在整个过程中,我经历了提交pr、规范标准(代码规范和图片规范)、自动化测试、交流经验,心理充满了激动和开心。

我希望,你也能亲手提交一些开源项目的pr,并在这其中理解开源文化的魅力。

\"CSDN开发云\"

ItVuer - 免责声明 - 关于我们 - 联系我们

本网站信息来源于互联网,如有侵权请联系:561261067@qq.com

桂ICP备16001015号