--- title: 如何提交好的PR-官方技术文章-鲲鹏社区 description: 用实例讲解，什么才是好的PR keywords: PR,如何提交好的,官方技术文章,鲲鹏社区,Bad,Example,Good,Request url: https://www.hikunpeng.com/developer/techArticles/20230809-5?envFlag=1 section: (其他) --- # 如何提交好的PR-官方技术文章-鲲鹏社区 URL: https://www.hikunpeng.com/developer/techArticles/20230809-5?envFlag=1 描述: 用实例讲解，什么才是好的PR 关键词: PR,如何提交好的,官方技术文章,鲲鹏社区,Bad,Example,Good,Request 官方技术文章 [了解详情](https://www.hikunpeng.com/zh/developer/techArticles) 如何提交好的PR 如何提交好的PR 发表于 2023/08/09 0 “一个成功的码农是从一个合格的PR开始的” [了解详情](https://bbs.huaweicloud.com/live/kunpeng_live/202107221930.html)，下文列出了关于该主题的一些摘要，完整的内容请查看视频原文。 如上图所示，所谓PR，即Pull Request（拉取需求），主要由以下几个部分组成：（1）题目（2）内容（3）评论、提交信息、文件信息等 为什么PR如此重要呢？因为它是开源世界大规模软件开发的基石，也是其最重要的流程点。 （1）它是质量保证体系的基石。PR是真正合入代码和更新的入口，直接影响到最终交付件的质量。 （2）它是大规模协作开发的基石。在一个互相不见面的“虚拟世界”，PR几乎是大家交流最重要的通道和“语言”。 （3）它是社区历史的记录。PR不会被删除（除非它所在的仓库被彻底删除），每一个PR都记录在了社区历史中，是社区文化的传承载体之一。 下面让我们来看几个“糟糕”的PR： ### 1. Bad PR Example1 这个PR主要的问题是无信息量，试问： （1）说要加入这位maintainer，但是为什么要加的是他而不是其他人？ （2）提交这个PR时该SIG项目不多，为什么要引入这么多maintainer？ （3）新加入的这个maintainer后续在项目中的分工和作用是什么？ 在后面的comment中提交者把这些信息都补全了，所以该PR最终被合入了。但是单看这个PR本身，这是个非常不合格的PR。 ### 2. Bad PR Example2 这个PR比第一个例子要好一点——题目写的很清楚，在描述中也做了部分解释。但审批者看到这个PR“先天”会提出以下问题： （1）为什么要这样建仓？我们对gcc版本10是重量级的开发吗？ （2）需不需要像kernel那样的组织形式？如果类似内核，那应该只有gcc这样的仓而通过分支来进行版本区分，而不是像这样一个版本一个仓。 所以对这些自然会遇到的问题在提交PR时就应有所解释。 ### 3. Bad PR Example3 这是一个“接近完美”的PR。 （1）题目写得非常清晰：引入一个软件包。 （2）主体内容对这个包做什么做了详细的解释，同时说明了上游社区活跃、Licence友好等情况。 但是，审批的人会问如下问题： 什么业务需要引入这个软件，不能只说这个软件好，“好”软件成千上万，为什么要单单引入这个？它和我们这个项目有什么关系？当然，提交者后面的回答补全了这些信息： 糟糕的PR会对世界产生什么影响呢？下面列出了几条： （1）极大地降低工作效率，增加无谓的资源消耗。 （2）延长审批时间，使提交者和审批者双向不满。 （3）影响产品交付质量。 那么，如何写一个好的PR？ （1）一个PR对应一个事情，不要把不同的事情放在一个PR中，保持PR的干净整洁。 （2）PR首要是说清楚why，就是原因，为什么会有这个PR，这个PR解决了什么问题。 （3）PR中的描述要清晰明了，讲清楚commit中的要点是什么。 （4）一般来说，一个PR必须要有一个issue对应，这样才能形成需求和开发代码之间的对应关系。任何进入代码仓的内容是需要有原因的。 ### 4. Good PR Example1 这是一个比较好的PR的例子，主要表现在： （1）题目清晰。 （2）内容的可读性好，比如说是分了3个部分，每个部分做什么讲的非常清晰。 （3）还注明了希望谁来检视。 需要说明一点的是，虽然以上用来演示的PR都是TC管理的PR（如建仓、管理流程等），更多偏向于技术审批类，但代码提交、特性开发、问题修正、文档写作等的PR，其本质要求都是一样的。 结束语： PR是码农成功的开始——一个PR写的好的码农未必能成长为一个伟大的码农，但是一个PR写不好的码农注定无法成为一个伟大的码农——让我们从写好每一PR开始吧！ 附：以下列出了一些比较差的PR及其评审者的回复，大家可以从中学习。 | 较差PR案例 | 链接 | | --- | ---| | 没有清理干净提交，含有无意义的文件 | https://gitee.com/openeuler/community/pulls/1848 | | 简单覆盖diff | https://gitee.com/src-openeuler/python-zeroconf/pulls/2 | | 依赖关系的建立，先要找全依赖，再提交主包 | https://gitee.com/src-openeuler/python-zope-interface/pulls/7 | | 没有空行，可读性差 | https://gitee.com/src-openeuler/perl-String-Util/pulls/1 | | 无效的URL | https://gitee.com/src-openeuler/python-adb-shell/pulls/1 | | 没有获取最新的版本 | https://gitee.com/src-openeuler/python-fisx/pulls/1 | | 一个事情分成了不同的PR提交 | https://gitee.com/openeuler/community/pulls/2496 | | 马虎大意的issue | https://gitee.com/open_euler/dashboard?issue_id=I42IR8https://gitee.com/openeuler/community/pulls/2548 | | 没有在老的PR上修改，新开PR，导致信息缺失 | https://gitee.com/openeuler/community/pulls/2559https://gitee.com/openeuler/community/pulls/2556 | | 完全覆盖式的PR | https://gitee.com/src-openeuler/python-astroid/pulls/5 | | 并没有检视最新的github的版本，只是采用了pypi中的版本 | https://gitee.com/src-openeuler/python-pure-sasl/pulls/1 | | master软件引入老版本分支 | https://gitee.com/openeuler/community/pulls/2616 | | conflict命令的引入 | https://gitee.com/openeuler/community/pulls/2583 | | changelog的描述“正确但无用” | https://gitee.com/src-openeuler/memleax/pulls/8https://gitee.com/src-openeuler/perl-Unicode-LineBreak/pulls/6 |