Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision | ||
| zh:submitting-patches [2019/12/27 03:30] – [1. Creating a patch] superice | zh:submitting-patches [2020/03/08 15:52] – [10. 签署工作] superice | ||
|---|---|---|---|
| Line 107: | Line 107: | ||
| 通常最好先记录自己在做什么,然后再做。文档编制过程通常会揭示可能的改进。请及时更新文档。 | 通常最好先记录自己在做什么,然后再做。文档编制过程通常会揭示可能的改进。请及时更新文档。 | ||
| ===== 创建和提交更改(补丁) ===== | ===== 创建和提交更改(补丁) ===== | ||
| - | Read [[: | + | 在提交补丁前,请仔细阅读 |
| - | For patches against external package sources, refer to the quilt howto at [[docs: | + | 对于外部软件包的补丁程序,请参阅[[docs: |
| - | + | ||
| - | Please read [[https:// | + | |
| + | 请阅读[[https:// | ||
| ==== 1. 创建补丁 ===== | ==== 1. 创建补丁 ===== | ||
| - | All changes to OpenWrt occur in the form of patches. | ||
| - | Patches should be based in the root trunk, not in any lower subdirectory. | + | OpenWRT的所有更改都以补丁的形式出现。 |
| - | Make sure your patch does not include any extra files which do not belong in a patch submission. Make sure to review your patch -after- you have generated it, to ensure accuracy. | + | 补丁应基于根目录,而不应位于任何较低的子目录中。 |
| - | If your changes produce a lot of deltas, you may want to look into splitting them into individual patches which modify things in logical stages. This will facilitate easier reviewing by other OpenWrt | + | 请确保您的补丁不包括任何额外文件, 确保在生成补丁后对其进行检查,以确保准确性。 |
| + | |||
| + | 如果您的更改产生大量增量,则可能需要研究将其拆分为单个补丁,这些补丁会在逻辑阶段进行修改。 这将有助于其他OpenWrt开发人员更轻松地进行检查,如果您希望补丁被接受,这非常重要。 | ||
| + | |||
| + | 您可以按照自己的喜好使用不同的工具创建补丁: | ||
| - | The tools you can use to create a patch, in order of preference, are: | ||
| * Git | * Git | ||
| * SVN | * SVN | ||
| * diff | * diff | ||
| - | To ease integration of smaller patches into trunk, developers can also make pull-requests into the Github | + | 为了简化将较小补丁集成到主干中的问题,开发人员还可以向Github主干树中进行拉取请求-这是对早期补丁工作流程的补充。 较大的补丁或需要进一步讨论的补丁仍应发送至openwrt-devel列表,在此处对其进行评审,并在某些时候提交到主干。 |
| + | |||
| + | |||
| + | ==== 2. 描述更改内容 ===== | ||
| + | |||
| + | 描述补丁的技术细节。 | ||
| + | |||
| + | 要尽可能具体。 最糟糕的描述可能包括诸如“对程序包X的更改”,“对程序包X的错误修复”或“此补丁包括针对平台X的更新。请申请。”之类的内容。 | ||
| + | |||
| + | 维护者将感谢您以一种“无需修改”格式编写您的补丁描述,这种“无需修改”格式的补丁可以直接作为OpenWRT源代码管理系统的提交使用。见下面的第十三章。 | ||
| + | |||
| + | |||
| + | 如果您的描述开始变长,则表明您可能需要拆分补丁。 请参阅下面的第3部分。 | ||
| + | |||
| + | 当您提交或重新提交补丁或补丁系列时,请包括完整的补丁说明和说明。 不要只是说这是补丁(系列)的N版本。 不要指望补丁合并者会引用较早的补丁版本或引用的URL来查找补丁说明并将其放入补丁中。 即,补丁(系列)及其说明应是独立的,非相互引用的。 这使补丁合并者和审核者都受益。 一些评论者甚至可能没有收到补丁的早期版本。 | ||
| + | |||
| + | 如果补丁修复了已记录的错误跟踪条目,请按编号引用该错误条目。 | ||
| + | |||
| + | |||
| + | |||
| + | ==== 3. 拆分更改内容 ===== | ||
| + | 将“__逻辑更改__”分开到单个补丁文件中。 | ||
| - | ==== 2. Describe your changes ===== | + | 例如,如果您的更改包括单个程序包的错误修复和增强功能,请将这些更改分为两个或多个补丁程序。 |
| - | Describe the technical detail of the change(s) your patch includes. | + | |
| - | Be as specific as possible. The WORST descriptions possible include things like " | + | 另一方面,如果您对多个文件进行了一次更改,则将这些更改分组到一个补丁中。 因此,单个“__逻辑更改__”包含在单个补丁中。 |
| - | The maintainer will thank you if you write your patch description in a form which can be used unmodified as a commit message for OpenWrt source code management system. See par.13, below. | + | 如果一个补丁依赖于另一个补丁才能完成更改,只需在补丁说明中注明“此补丁取决于补丁X”。 |
| - | If your description starts to get long, that's a sign that you probably need to split up your patch. See par.3, next. | + | 如果您不能将补丁集压缩为更小的补丁集,则一次仅发布15个左右,然后等待审核和集成。 |
| - | When you submit or resubmit a patch or patch series, include the complete patch description and justification for it. Don't just say that this is version N of the patch (series). Don't expect the patch merger to refer back to earlier patch versions or referenced URLs to find the patch description and put that into the patch. I.e., the patch (series) and its description should be self-contained. This benefits both the patch merger(s) and reviewers. Some reviewers probably didn't even receive earlier versions of the patch. | + | ==== 4. 更改内容格式检查 ===== |
| - | If the patch fixes a logged bug trac entry, refer to that bug entry by number. | + | 检查您的补丁程序是否存在“基本样式”冲突。 否则,只会浪费审阅者的时间,并且会拒绝您的补丁,甚至可能不会被阅读。 |
| + | ==== 5. 选择邮件目的地 ===== | ||
| + | 请查看Makefile,是否存在MAINTAINER宏。 如果存在,则请给该人发送电子邮件。 除非您有理由不这样做,否则请始终CC openwrt-devel <at> list.openwrt.org。 如果未列出维护者,请将补丁发送到[[https:// | ||
| + | ==== 6. 不要使用MIME类型邮件,不要使用超连接方式,不要压缩补丁,不要使用附件方式,只使用纯文本 ===== | ||
| - | ==== 3. Separate your changes ===== | + | OpenWrt开发人员需要能够阅读和评论您提交的更改。 对于OpenWrt开发人员而言,使用标准的电子邮件工具“引用”您的更改非常重要,这样他们就可以对代码的特定部分进行注释。 |
| - | Separate __logical changes__ into a single patch file. | + | |
| - | For example, if your changes include both bug fixes and enhancements for a single package, separate those changes into two or more patches. | + | 因此,所有补丁都应“内联”提交电子邮件。 警告:如果您选择剪切粘贴,请小心编辑器的自动换行会损坏您的补丁程序。 |
| - | On the other hand, if you make a single change to numerous files, group those changes into a single patch. Thus a single logical change is contained within a single patch. | + | 不要将补丁附加为MIME附件,或者压缩。许多流行的电子邮件应用程序并不总是将MIME附件作为纯文本发送,使得无法对代码进行注释。 |
| - | If one patch depends on another patch in order for a change to be complete, that is OK. Simply note "this patch depends on patch X" in your patch description. | + | 例外:如果您的邮件发送者正在处理补丁程序,则有人可能会要求你使用MIME重新发送补丁程序。 |
| - | If you cannot condense your patch set into a smaller set of patches, then only post say 15 or so at a time and wait for review and integration. | + | Mozilla雷鸟要求您更改电子邮件默认值以发送纯文本电子邮件。[[http:// |
| - | ==== 4. Style check your changes ===== | ||
| - | Check your patch for basic style violations. Failure to do so simply wastes the reviewer' | ||
| - | ==== 5. Select email destination | + | ==== 7. 邮件大小 |
| - | Look in the Makefile if a MAINTAINER macro exists. If so, email that person. Unless you have a reason NOT to do so, always CC openwrt-devel <at> lists.openwrt.org. If no maintainer is listed, send your patch to the [[https:// | + | |
| - | ==== 6. No MIME, no links, no compression, | + | 较大的更改不适用于邮件列表和某些维护者。 如果未压缩的补丁程序大小超过300 kB,则最好将补丁程序存储在可访问Internet的服务器上,并提供指向补丁程序的URL (链接) |
| - | OpenWrt developers need to be able to read and comment on the changes you are submitting. It is important for an OpenWrt developer to be able to " | + | ==== 8. 不要灰心,重新提交 |
| - | For this reason, all patches should be submitting email " | + | 提交更改后,请耐心等待。 如果开发人员喜欢你的更改并应用它,它将在源代码管理系统中显示为新修订。 |
| - | Do not attach the patch as a MIME attachment, compressed or not. Many popular email applications will not always transmit a MIME attachment as plain text, making it impossible to comment on your code. | + | 但是,如果你的更改未出现在源代码管理系统中,则可能有多种原因。 缩小这些原因,纠正错误,然后提交更新的更改是你的工作。 |
| - | Exception: If your mailer is mangling patches then someone may ask you to re-send them using MIME. | + | 有时,开发人员可能会“丢弃”你的补丁,而有或没有评论。 这就是系统的本质。 如果你的补丁程序被删除,则可能是由于: |
| - | Mozilla Thunderbird requires that you change email defaults to send plain text email. | + | * 你的补丁不适用于最新的OpenWrt版本。 |
| - | read [[http:// | + | * 你的补丁在openwrt-devel上没有得到充分讨论。 |
| - | :!: disable flowed text | + | * 样式问题。 |
| + | * 电子邮件格式问题(请重新阅读本节)。 | ||
| + | * 你的更改存在技术问题。 | ||
| + | * 他们收到大量电子邮件,而你的邮件迷失了。 | ||
| + | * 你真烦人。 | ||
| - | ==== 7. Email size ===== | ||
| - | Large changes are not appropriate for mailing lists, and some maintainers. If your patch, uncompressed, | ||
| - | ==== 8. Don't get discouraged, | + | 如有疑问,请在openwrt-devel邮件列表上征求意见。 |
| - | After you have submitted your change, be patient and wait. If developers like your change and apply it, it will appear as new revision in the source code management system. | + | |
| - | However, if your change doesn' | ||
| - | Sometimes, developers may " | + | ==== 9. 在邮件主题中包含PTACH提示 ===== |
| - | * Your patch did not apply cleanly to the latest OpenWrt revision. | + | |
| - | * Your patch was not sufficiently discussed on openwrt-devel. | + | |
| - | * A style issue. | + | |
| - | * An email formatting issue (re-read this section). | + | |
| - | * A technical problem with your change. | + | |
| - | * They get tons of email, and yours got lost in the shuffle. | + | |
| - | * You are being annoying. | + | |
| - | When in doubt, solicit comments on openwrt-devel | + | 由于openwrt-devel的电子邮件流量很高,因此通常会在主题行前加上[PATCH]作为前缀。 这样,OpenWrt开发人员可以更轻松地将补丁与其他电子邮件讨论区分开来,并且还将自动进入补丁工作。 |
| - | ==== 9. Include PATCH in the subject | + | ==== 10. 签署工作 |
| - | Due to high email traffic to openwrt-devel, | + | |
| - | ==== 10. Sign your work ===== | + | 为了跟踪谁做了什么,我们对正在通过电子邮件发送的补丁程序使用“签署”程序。 |
| - | To provide tracking of who did what, we use a " | + | |
| - | The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below: | + | 补丁说明末尾的签名很简单,它证明您写了它,或者有权将它作为开放源代码补丁进行传递。 规则非常简单:如果您可以证明以下内容: |
| < | < | ||
| Line 227: | Line 238: | ||
| </ | </ | ||
| - | then you just add a line saying | + | 然后你只需加上一句话 |
| <code bash> | <code bash> | ||
| Line 233: | Line 244: | ||
| </ | </ | ||
| - | using your real name (no pseudonyms or anonymous contributions.) | + | 使用您的真实姓名(没有化名或匿名。) |
| - | If you are a package or target maintainer, sometimes you need to slightly modify patches you receive in order to merge them, because the code is not exactly the same in your tree and the submitters' | + | 如果你是一个包或目标维护者,有时你需要稍微修改你接收到的补丁以便合并它们,因为代码在你的树和提交者中不是完全相同的。如果你严格遵守规则,你应该向提交人请求重新授权,但这完全是浪费时间和精力。规则(B)允许您调整代码,但是更改提交人的代码并使他支持您的bug是非常不礼貌的。为了解决这个问题,建议您在最后一个签名的头和您的头之间添加一行,说明您的更改的性质。虽然没有什么强制性的,这似乎是准备描述与您的邮件和/或名称,所有包围在方括号中,是显而易见的,足以使你清楚,你负责的最后一分钟的变化。例子: |
| <code bash> | <code bash> | ||
| Line 243: | Line 254: | ||
| </ | </ | ||
| - | This practice is particularly helpful if you maintain a stable branch and want at the same time to credit the author, track changes, merge the fix, and protect the submitter from complaints. Note that under no circumstances can you change the author' | + | 如果你保持一个稳定的分支,并希望同时信任作者,跟踪更改,合并修复,并保护提交者不受投诉,这种做法尤其有用。请注意,在任何情况下,您都不能更改作者的身份(从报头),因为它是在变更日志中出现的身份。 |
| - | Special note to back-porters: | + | 向后移植者的特别注意:在提交消息的顶部(仅在主题行之后)插入补丁来源的指示,以方便跟踪,这似乎是一种常见且有用的做法。 例如: |
| <code bash> | <code bash> | ||
| Line 253: | Line 264: | ||
| </ | </ | ||
| - | Whatever the format, this information provides valuable help to people tracking your trees, and to people trying to trouble-shoot bugs in your tree. | + | 无论采用哪种格式,此信息都可以为跟踪您的树的人们以及试图对树中的错误进行故障排除的人们提供宝贵的帮助。 |
| - | For the more convenient developers, | + | 对于更方便的开发人员,git可以自动添加签名: |
| <code bash> | <code bash> | ||
| Line 261: | Line 272: | ||
| </ | </ | ||
| - | ==== 11. When to use " | + | ==== 11. 什么时候使用" |
| The Signed-off-by: | The Signed-off-by: | ||
| Line 274: | Line 285: | ||
| If a person has had the opportunity to comment on a patch, but has not provided such comments, you may optionally add a " | If a person has had the opportunity to comment on a patch, but has not provided such comments, you may optionally add a " | ||
| - | ==== 12. Using " | + | ==== 12. 使用 |
| If this patch fixes a problem reported by somebody else, consider adding a Reported-by: | If this patch fixes a problem reported by somebody else, consider adding a Reported-by: | ||
| Line 307: | Line 318: | ||
| A Reviewed-by tag is a statement of opinion that the patch is an appropriate modification of OpenWrt without any remaining serious technical issues. Any interested reviewer (who has done the work) can offer a Reviewed-by tag for a patch. This tag serves to give credit to reviewers and to inform maintainers of the degree of review which has been done on the patch. Reviewed-by: | A Reviewed-by tag is a statement of opinion that the patch is an appropriate modification of OpenWrt without any remaining serious technical issues. Any interested reviewer (who has done the work) can offer a Reviewed-by tag for a patch. This tag serves to give credit to reviewers and to inform maintainers of the degree of review which has been done on the patch. Reviewed-by: | ||
| - | ==== 13. The canonical patch format | + | ==== 13. 规范补丁格式 |
| The canonical patch subject line is: | The canonical patch subject line is: | ||
| Line 368: | Line 379: | ||
| ===== 参考 ====== | ===== 参考 ====== | ||
| * Andrew Morton, "The perfect patch" (tpp). | * Andrew Morton, "The perfect patch" (tpp). | ||
| + | * https:// | ||
| * http:// | * http:// | ||
| * Jeff Garzik, "Linux kernel patch submission format" | * Jeff Garzik, "Linux kernel patch submission format" | ||