Next: , Previous: , Up: 贡献   [Contents][Index]


22.6 提交补丁

Development is done using the Git distributed version control system. Thus, access to the repository is not strictly necessary. We welcome contributions in the form of patches as produced by git format-patch sent to the guix-patches@gnu.org mailing list (see Submitting patches to a project in Git User Manual). Contributors are encouraged to take a moment to set some Git repository options (see 配置Git) first, which can improve the readability of patches. Seasoned Guix developers may also want to look at the section on commit access (see 提交权利).

This mailing list is backed by a Debbugs instance, which allows us to keep track of submissions (see 跟踪程序漏洞和补丁). Each message sent to that mailing list gets a new tracking number assigned; people can then follow up on the submission by sending email to ISSUE_NUMBER@debbugs.gnu.org, where ISSUE_NUMBER is the tracking number (see 发送补丁系列).

请以ChangeLog格式(see Change Logs in GNU代码规范)写commit日志;你可以浏览commit历史里的例子。

提交添加或者修改软件包定义的补丁之前,请过一遍这个检查列表:

  1. 如果软件包的作者为发布的文件包提供了密码学签名,请验证文件的真实性。对于独立的 GPG 签名文件,这可以通过 gpg --verify 命令完成。
  2. 花些时间为软件包提供一个合适的简介和描述。更多指导,See 简介和描述
  3. 运行guix lint 软件包软件包是新添加的或修改过的软件包的名字,修复它报告的错误(see Invoking guix lint)。
  4. Run guix style package to format the new package definition according to the project’s conventions (see Invoking guix style).
  5. guix build 软件包命令确保这个软件包可以在你的平台上构建。
  6. We recommend you also try building the package on other supported platforms. As you may not have access to actual hardware platforms, we recommend using the qemu-binfmt-service-type to emulate them. In order to enable it, add the virtualization service module and the following service to the list of services in your operating-system configuration:
    (service qemu-binfmt-service-type
     (qemu-binfmt-configuration
       (platforms (lookup-qemu-platforms "arm" "aarch64"))))
    

    然后重新配置你的系统。

    You can then build packages for different platforms by specifying the --system option. For example, to build the "hello" package for the armhf or aarch64 architectures, you would run the following commands, respectively:

    guix build --system=armhf-linux --rounds=2 hello
    guix build --system=aarch64-linux --rounds=2 hello
    
  7. 请确保软件包里不捆绑出现已经被打过包的软件的副本。

    有时,软件包为了方便用户,捆绑了依赖库的源代码。然而,当依赖库在发行版里已经存在时,做为一个发行版,我们希望确保这些软件包使用发行版里已有的副本。这提高资源使用率(依赖库只构建一次,存储一份),并且使发行版更容易管理,如仅在一个地方对某个软件包进行安全更新就可以影响整个系统--捆绑软件会妨碍这么做。

  8. Take a look at the profile reported by guix size (see Invoking guix size). This will allow you to notice references to other packages unwillingly retained. It may also help determine whether to split the package (see 有多个输出的软件包), and which optional dependencies should be used. In particular, avoid adding texlive as a dependency: because of its extreme size, use the texlive-tiny package or texlive-union procedure instead.
  9. For important changes, check that dependent packages (if applicable) are not affected by the change; guix refresh --list-dependent package will help you do that (see Invoking guix refresh).

    取决于受影响的软件包的数量,即需要重新构建的数量,commit需要被提交到不同的分支,具体如下:

    300个或更少的受影响的软件包

    master分支(非破坏性的更改)。

    300 至 1800 个受影响的软件包

    staging branch (non-disruptive changes). This branch is intended to be merged in master every 6 weeks or so. Topical changes (e.g., an update of the GNOME stack) can instead go to a specific branch (say, gnome-updates). This branch is not expected to be buildable or usable until late in its development process.

    超过 1800 个受影响的软件包

    core-updates branch (may include major and potentially disruptive changes). This branch is intended to be merged in master every 6 months or so. This branch is not expected to be buildable or usable until late in its development process.

    All these branches are tracked by our build farm and merged into master once everything has been successfully built. This allows us to fix issues before they hit users, and to reduce the window during which pre-built binaries are not available.

    When we decide to start building the staging or core-updates branches, they will be forked and renamed with the suffix -frozen, at which time only bug fixes may be pushed to the frozen branches. The core-updates and staging branches will remain open to accept patches for the next cycle. Please ask on the mailing list or IRC if unsure where to place a patch.

  10. 检查软件包的构建过程是不是确定性的。这通常意味着检查对软件包的独立构建是否能得到每一个比特都完全相同的结果。

    为此,一个简单的做法是在你的机器上多次构建同一个软件包(see 调用guix build):

    guix build --rounds=2 <我的软件包>
    

    这足以查出一批普通的不确定性问题,如构建结果里存在时间戳或随机生成的输出。

    Another option is to use guix challenge (see Invoking guix challenge). You may run it once the package has been committed and built by ci.guix.gnu.org to check whether it obtains the same result as you did. Better yet: Find another machine that can build it and run guix publish. Since the remote build machine is likely different from yours, this can catch non-determinism issues related to the hardware—e.g., use of different instruction set extensions—or to the operating system kernel—e.g., reliance on uname or /proc files.

  11. 在编写文档时,请用性别中立的词语指代人,如“他”, “他的”,等。
  12. 检查你的补丁只包含一些相关的更改。把不相关的更改捆绑在一起会让评审更困难和更慢。

    不相关的更改的例子有:同时新增多个软件包,或更新软件包同时修补这个软件包。

  13. Please follow our code formatting rules, possibly running guix style script to do that automatically for you (see 格式化代码).
  14. 当可能时,请在源URL里使用镜像see Invoking guix download。使用可靠的而不是生成的URL。例如,GitHub的下载文件每次生成时不一定是相同的,所以这时最好克隆仓库。不要在URL里使用name变量:这没有什么用,而且如果名字变了,URL很可能就错了。
  15. Check if Guix builds (see 从Git构建) and address the warnings, especially those about use of undefined symbols.
  16. Make sure your changes do not break Guix and simulate a guix pull with:
    guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
    

When posting a patch to the mailing list, use ‘[PATCH] …’ as a subject, if your patch is to be applied on a branch other than master, say core-updates, specify it in the subject like ‘[PATCH core-updates] …’.

You may use your email client or the git send-email command (see 发送补丁系列). We prefer to get patches in plain text messages, either inline or as MIME attachments. You are advised to pay attention if your email client changes anything like line breaks or indentation which could potentially break the patches.

Expect some delay when you submit your very first patch to guix-patches@gnu.org. You have to wait until you get an acknowledgement with the assigned tracking number. Future acknowledgements should not be delayed.

When a bug is resolved, please close the thread by sending an email to ISSUE_NUMBER-done@debbugs.gnu.org.


Next: 跟踪程序漏洞和补丁, Previous: 代码风格, Up: 贡献   [Contents][Index]