Skip to content

开始项目贡献和社区交流前必要学习的概念

Jump to bottom Edit New page
rvalue edited this page Oct 30, 2023 · 14 revisions

archriscv-packages 的社区地位

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

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

关于社区

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

摘自吴伟老师的致信

......前略

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

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

Be Humble.

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

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

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

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

除此之外，在报 log 之前，不妨把问题先在群里放出来和前辈们讨论讨论。写完了 bug report 之后也可以放到群里问问，问问前辈们看看是否有措辞不妥，信息不充分之类的问题。特别地，如果你是还未成为正式实习生的新同学，可以在公开的「Arch Linux RISC-V 中文社区」群组中找到与我们的即时通讯渠道。不要介意打破沉默——我们经常在线，欢迎你的提问与交流！

关于合作

  • 善用搜索

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

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

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

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

  • 避免 X-Y 问题

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

有关 X-Y 问题更详细的定义和缺点可以查看这篇文章：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 的汇报链接也算作贡献的一部分。

  • 如何给 Arch Linux 报 BUG

首先请通读这篇 wiki https://wiki.archlinux.org/title/Bug_reporting_guidelines 了解基本概念。 在 https://archlinux.org/packages/ 搜索要报 BUG 的包，详情页的右边有一个 Package Action 的小方框。点击其中第二行第一个 "Bug Reports"，看看有没有人已经提交类似的 BUG。如果有就可以等着了。（除非这个包作为依赖，目前卡住了很多其他关键的软件> 包，这个时候可以自己动手修一修，增加贡献的含金量）

如果没有人提交过相似的 BUG，那么点击第二行第二个 "Add New Bug"，新的页面会生成好模板， 按照提示填写即可。左边的那些菜单项不用自己修改。

如果是普通的无法构建，SUMMARY 那一行填 FTBFS: （简短的编译错误摘要） 即可，然后在底下详细描写遇到了什么错误。 如果已经有可用的修复补丁，可以把 patch 上传到附件。

如果是 outdated 的包，不要报 BUG。在 Package Action 那一栏有 "Flag Package Out-of-Date" 的功能。

注意：请不要用中文报 bug !!!

给所有的修改注释

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

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

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

  1. 每一次修改都从 master 分支的头创建一个新的分支，通常我们用包的名字来当分支名。
  2. 创建一个和包名字同名的文件夹。把 git diff 生成的，对 PKGBUILD 的补丁放进名为 riscv64.patch 文件，并放入这个文件夹里。对源码修改的 patch 也放进这个文件夹里。
  3. 按照上面的规范，认真做好 commit 并发起 PR

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

Commit Title

  • 如果当前仓库没有这个包的 patch，标题用 addpatch: pkgname
  • 如果这个 PR 是对原有包的修改，标题用 updpatch: pkgname
  • 如果这个 PR 是删除掉仓库内的 patch，标题用 rmvpatch: pkgname
  • 如果这个 PR 是对 qemu-user-blacklist.txt 的修改，标题用 qemu-user-blacklist: 加上具体修改内容，例：qemu-user-blacklist: add pkgname

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

曾经的标题格式

以前采用的是下面这套标签：

  • addpkg
  • updpkg / upgpkg
  • rmvpkg

出于向前兼容的考虑，这些标签仍然能够被正常识别，但是它们不太符合本仓库的本质，所以更推荐使用上面提到的格式。

数组的格式

source=("http://www.frodo.looijaard.name/system/files/software/${pkgname}/${pkgname}-${pkgver}.tar.gz"
        "psiconv.patch") # <- 注意括号要跟在最后一个文件后，不要创建新行
       #^
       # 注意这里要对齐

md5sums=('286e427b10f4d10aaeef1944210a2ea6'
         '4fb974d3ae3058de435050d1595f269b')

Reference: https://github.com/felixonmars/archriscv-packages/pull/148/commits/839b90f662cc942f9c1b1f80284d93e4d48dd5a5

不要提交对 arch 的修改

肥猫的构建脚本会把这个处理好，在 PR 的时候不用提交对 arch 的修改。

Reference: https://github.com/felixonmars/archriscv-packages/pull/488/commits/116365a132e9e973ab152514d59ed6688fdc3799

其他规范

source 上游文件名问题

建议给 src 引用的文件取独特的名字，比如

${pkgname}-xxxpatch::https://...

因为从 source 数组里下载的文件都会放进 SRCDEST 里，有概率和别的包下载的东西同名， 然后 archbuild 以为下载过了就直接用，然后 checksum 就对不上了。

上游已经修复编译错误但还没发版本

记得测试一下 x86 会不会有编译失败的问题，优先给 Arch Linux 提交补丁。

  • 用 cherry-pick
 prepare() {
   cd $pkgname
+  git cherry-pick -n 508c0f94e5f182e50ff61be6e04f72574dee97cb  # patch: Don't alter or try to write [GtkChild] fields
+  git cherry-pick -n e8a0aeec350ea80349582142c0e8e3cd3f1bce38  # patch: Reference of [GtkChild] fields is handled by GtkBuilder, type must be unowned
 }
  • 直接从上游下载 patch
+source=(https://github.com/MegaGlest/megaglest-source/releases/download/${pkgver}/megaglest-source-${pkgver}.tar.xz{,.asc}
+        ftp-fixes.patch::https://github.com/MegaGlest/megaglest-source/commit/5a3520540276a6fd06f7c88e571b6462978e3eab.patch)

+prepare() {
+  cd megaglest-${pkgver}
+
+  patch -Np1 -i ../ftp-fixes.patch
+}

参考:

Tips: 如何把 PR 的内容以 patch 形式下载

找到 PR 的那条 commit，在 URL 后边加 .patch/.diff 就能拿到 raw contents。 比如 PR #470, 去掉 commit 后的那一串，直接加上 .diff。

-...kages/pull/470/commits/95242a8b610854ef64c8b5e304756ba6a4d4302d

+...kages/pull/470.diff
推荐使用 .diff GitHub 的 .patch 包含的 patch 头是从 PR 生成的，很可能发生变动，导致打包时下载的 patch 与预先提供的 checksum 不一致。

修改 PKGREL

pkgrel 不能超过 x86 主线，如果需要重新打包，推荐以 0.1 为递增值逐次往上加。

Add a custom footer
heading
Clone this wiki locally