Skip to content

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

Avimitin Lu edited this page Oct 30, 2023 · 14 revisions

如何提交代码修复

1. 上游优先级最高

你对软件包的源代码的所有修改都优先提交给上游,如果上游很活跃,并且在短期合并了你的 patch,可以等待上游发版本。 提交给上游的补丁在你对你贡献的评估时会占很大的比重。

如果上游已经长期失联/不积极修复 BUG/因为特殊原因拒绝了你的补丁,你可以在 PKGBUILD 里引用你发给上游的补丁链接, 并把这个对 PKGBUILD 的修改发到这个仓库里。

如果这个软件包在 Arch Linux 主线(x86_64) 下也 FTBFS,请记得到 Arch Linux 报 BUG。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 !!!

2. 给所有的修改注释

一定在 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

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

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

数组的格式

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 不一致。

本地版本过老

假设上一次发布的版本特别老,主线做了很多修改,然后引用的修复 patch 行数不对应, 和源码冲突的话,优先发 issue 催上游发新版本。

修改 PKGREL

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

Clone this wiki locally