Skip to content

Essential Concepts to Learn Before Contributing

Jump to bottom
wszqkzqk edited this page Dec 21, 2024 · 7 revisions

项目名称

本项目有以下名称或别称，这些名称或别称主要因历史原因或格式要求而存在，均可指代本项目：

  • Arch Linux for Loong64
  • Arch Linux for Loongarch64
  • Arch Linux LoongArch
  • Loong Arch Linux
  • archloong
  • Arch Loong64 Port

目前这些概念完全相同。总之，本项目是Arch Linux针对loong64架构的移植版本。

社区地位

首先需要理解一下这个仓库与好几个上游之间的关系。

  • loongarch-packages, Arch Linux的下游，但和Arch Linux官方没有任何关系。loongarch-packages 只 用来存一些loong64架构特定的编译修复。
  • Arch Linux Official, Arch Linux x86_64主线，通常方便的说法都称之为 “Arch 上游”
  • Upstream，在目前语境中指代软件的来源，是真正意义上的上游。

关于社区

  • 以谦虚的心态进入开源社区

摘自吴伟老师的致信

......前略

随着规模的扩大，我们每一个人都需要更加注意，在推动开源社区支持RISC-V的同时，一定要避免作为外来者对开源软件社区造成侵扰。 具体行为例子包含（但不限于）：在没有搞清楚开源社区的运作流程和社区风格的情况下就贸然提出流程改进等要求； 在没有对开源社区做出足够贡献的前期下就开始要求获得超过新人的权限； 为了让自己的RISC-V支持进入下一个版本而公开或私下要求延期版本发布流程或简化接收标准等。

以上是一些例子，从总体而言，在行为模式上尤其要避免「教社区如何做事」、「软磨硬泡」以及「为我开后门或特例」的做法。 每个社区都有自己长期合作积累下来的规则和流程，请各位务必以谦卑的心态去学习、融入、贡献。

Be Humble.

  • 一些减少沟通成本的注意事项

首先在给社区做贡献之前，一定要优先看上游的 Code of conduct/How to contribute 等指引，尽可能的按照上游的习惯去合作。 其次和社区沟通时，尽量减少提 “某某错误是在给 loongarch-packages 做修复时出现的”，也不要用 loongarch-packages 这边的习惯做法去和上游对峙。在和上游沟通时，只需要提软件错误相关的必要信息即可。更不要不知所谓的丢个 loongarch-package 的修复链接给上游，敷衍了事的报个 bug，这样会损害整个项目的社区声誉。

如果没有经验，或者不知道怎么和上游反馈比较好，可以参照这样的思维模式来沟通：

  1. 完整，详细的错误信息。如果非常的长可以考虑使用 github gist 或其他 pastebin 服务，不要把一整串 log 丢 issue 主页，刷屏会影响上游的好感。
  2. 软件包是在什么架构，什么系统，什么机器上出现的异常。
  3. 补充软件包的版本，是否有打其他补丁等等信息。
  4. 这个问题是否在其他架构上可复现？还是仅有在 loong64 上出现？

除此之外，在报 log 之前，不妨把问题先在群里放出来讨论讨论。写完了 bug report 之后也可以放到群里问问，问问其他人看看是否有措辞不妥，信息不充分之类的问题。

关于合作

  • 善用搜索

不耻下问虽然是一种被推崇的学习态度，但在开源合作时，过于频繁且没有价值的询问会浪费所有参与者的时间。

在修包的过程中，每次问问题之前都先询问自己：

  • 「我查过 PR 和 Commit History 了吗？」
  • 「我查过这个软件包的社区 issues 或者邮件历史了吗？」
  • 「我查过这个软件的文档了吗？」
  • 「不懂的地方，我看过他的源码实现了吗？」
  • 「这个问题在群里曾经讨论过了吗？我有查过聊天记录吗？」
  • 「这个问题在 wiki 或者别的地方有记录过吗？」
  • 「我有用搜索引擎查过相关的资料或者内容了吗？」

而在和社区交流时，也有类似的需要注意的问题，详细请阅读《提问的艺术》

  • 避免 X-Y 问题

在问问题的时候，首先要提出自己为什么会有这个需求，而不是询问某个实现如何达成。X-Y 问题不仅浪费参与者的时间，也容易误导其他参与讨论的人，即使最终得出结论，其也不一定是最佳解决方案。

有关 X-Y 问题更详细的定义和缺点可以查看这篇文章：https://web.archive.org/web/20230619024531/https://coolshell.cn/articles/10804.html

什么时候给什么仓库提交代码修复

对软件包的 源代码 的所有修改都 优先 提交给上游，如果上游很活跃，并且在短期合并了这个修复补丁，可以等待上游发版本。 提交给上游的补丁在本项目看来是更加有价值的贡献。

只有在 上游已经长期失联/不积极修复 BUG/发版周期特别漫长/因为特殊原因拒绝了补丁/这个软件包目前作为依赖，卡住了很多其他的软件包 的情况下，可以在 PKGBUILD 里引用发给上游的补丁链接，并把这个对 PKGBUILD 的修改发到这个仓库里。

如果发给上游的补丁需要做一些修改才能打到目前 Arch 的版本上，比如补丁是对着 master HEAD 写的，但是 Arch 用的旧版本代码和 HEAD 有相当多的差异。这个时候可以把 PKGBUILD 的修改对源代码的补丁一起提交到仓库，并在 commit 上写下原因，以及补丁对应的上游链接。同时尽量催促上游发布新版本。

如果这个软件包在 Arch Linux 主线（x86_64) 下也 FTBFS，请先到 Arch Linux 报 BUG，即使有修复补丁，也在 bug report 里一并提交给 Arch 上游。BUG 的汇报链接也算作贡献的一部分。

给所有的修改注释

一定在 commit message，或者 pr 里写清楚修改的原因。比如“这个 PR 能修复什么编译错误”，“为什么要加上这个新的依赖”，“为什么要多加这么一行参数”等等。 讲清楚“为什么”属于我们工作流的一部分。一是为了以后方便维护，不会看着一个完全没有注释的修改，摸不着头脑。 还有就是能帮助新人，让他们来仓库查相关错误时能通过编译错误，检索到相关的修复方法。

在 PKGBUILD 中也一定要注释清楚修改原因，比如添加 make 参数， 修改 cflags 之类的，添加上“这么做能修好什么”相关的注释。

提交 PR 的一些格式注意事项

  1. 每一次修改都从 master 分支的头创建一个新的分支，通常我们用包的名字来当分支名。
  2. 创建一个和包名字同名的文件夹。把 export-loong64-patches 生成的 loong.patch 和导出的其他补丁放进这个文件夹里。
  3. 按照上面的规范，认真做好 commit 并发起 PR。

一般我们青睐一个 PR 只带一个 commit，如果一个 PR 内有多次修改，请 rebase/squash 并 force push（或新开 PR）。

Commit Title

  • 如果当前仓库没有这个包的 patch，标题用 addpatch: pkgbase, ver=xxx
  • 如果这个 PR 是对原有包的修改，标题用 updpatch: pkgbase, ver=xxx
  • 如果这个 PR 是删除掉仓库内的 patch，标题用 rmvpatch: pkgbase, ver=xxx

请注意标题里的冒号附近需要空一格，再写包名。 同时强烈建议不要只用 git commit -m "title"，建议在 commit body 里写清楚这次修改的内容和原因。

Clone this wiki locally