Contribution Guidelines for Developers

Gary Wang edited this page Dec 29, 2018 · 19 revisions

开发者代码贡献指南

欢迎大家积极贡献代码以使 Deepin 变得更加完善!下面是一份简易指南。

注:文档待更新。我们计划逐步将项目代码审核和协作平台从现在的 Gerrit 迁移到 GitHub,在迁移完成之前,对于依然没有完成迁移的项目,请参考下面的步骤提交你的 Patch,对于已经迁移到 GitHub 的项目,你可以直接通过 GitHub Pull Request 提交你的 Patch,请参见本 Wiki 最后的附注了解已经迁移到 GitHub 的项目列表

贡献者代码约定

所有的 Deepin 项目均遵从 Contributor Covenant 1.2 代码约定,默认情 况下我们认为开发者已经同意这份约定。任何疑问请咨询 support@deepin.com

获取代码

Deepin 所有的代码均保存在自己的 Gerrit 代码审查平台,并且会实时同步 到 GitHub 以方便浏览,所以到其中任意一个下载源码均可。

但作为一个通用的官方代码审查平台,我们更期望开发者直接使用 Gerrit 来推送代码合并请求,或者使用 GitHub,Deepin 的仓库管理人员会将请求 导入到 Gerrit。具体流程请参见下文。

配置 Gerrit

注:该步骤已过时,当你使用 GitHub 登录 Gerrit 时,你的 GitHub 账号需要至少设置有一个公开的邮箱,我们的 Gerrit 读取这些邮箱用作配置你的可用邮箱。另外,在 Gerrit 重设你的主要邮箱时可能提示错误,此时重新登录 Gerrit 即可生效

  1. 使用 GitHub 帐号登录 Deepin Gerrit
  2. 选择页面顶部 GitHub->Profile 手动导入帐号信息。直接点击 Next 即可,成功后会跳转到一个空白页面。可以重复执行该步骤以保证使用最新的 GitHub 帐号信息。 请勿跳过该步骤 ,否则稍后提交 review 时会因电子邮箱地址不匹配而无法将提交推送至服务器。
  3. 在本地安装 git-review 工具,例如在 Debian 下可以执行下面的命令:
    sudo apt-get install git-review
        
  4. 创建 ~/.config/git-review/git-review.conf 并写入下面的内容以保 证某些项目默认不包含 .gitreview 配置文件时执行 git-review 命 令时可以正常工作
    [gerrit]
    defaultremote = origin
        

    ps: 除了使用git-review.conf外亦可通过git review -r origin 来手动指定review的remote

提交代码

  1. 克隆目标项目

    需要注意,请使用 Gerrit 项目描述页面下提供的 Clone with commit-msg hook + ssh Git 克隆命令,如

    git clone ssh://<user>@cr.deepin.io:29418/deepin-music && \
      scp -p -P 29418 <user>@cr.deepin.io:hooks/commit-msg deepin-music/.git/hooks/
        
  2. 建立新分支

    首先要在本地创建一个新的分支用于写代码,分支名称须以 contrib/ 作 为前缀,例如 contrib/network/bug/conn-missedcontrib/display/dev/support-multi-monitors ,具体请参考 分支命名规范

  3. 编写代码

    开始写代码前,强烈建议先阅读我们的代码规范以保证统一的代码风格, 可以到分类页面寻找相关文档。同时建议阅读项目下的 HACKING 文档以 获取更多有用的信息。

  4. 测试

    如果可能,建议为新加入的代码编写单元测试,并且在本地执行一遍所有 测试,如果测试均通过,将对于代码被上游接收有很大帮助。

  5. 编写 Git 提交日志

    Git 提交日志编写时也应遵从一定的原则,如第一行标题不应超过 50 个字符, 正文使用 72 个字符作为缩进等,具体请参考 Git 提交日志编写规范

  6. 代码审查

    所有准备工作就绪后,可以到 Git 目录执行下面的命令将代码提交到 Gerrit 对应的 项目分支,以分支 master 为例

    git review master
        

    命令执行成功后,会输出一个 URL 用于审查代码,默认 Gerrit 会根据 当前项目自动添加审查人员,也可以手动添加人员帮你审查代码。

    代码审查包括下面四个部分:

    1. Code-Review:审查主题代码,只有审查者 +2 后才能合并代码
    2. Verified:审查能否通过测试,一般由 jenkins 持续集成框架自动执 行,只有 +1 后才能合并代码
    3. build-config:可选,若更改打包相关的文件(如 debian 目录), 须经过包管理人员进行审查
    4. i18n:可选,若涉及到国际化的问题,须经过翻译人员进行审查

    注意:若需要对代码进行二次更改,执行 git commit --amend 命令将 变更合并到上一个提交,然后重新执行 git review 命令更新 Gerrit 上的代码

  7. 合并代码

    代码审查通过后,由上游开发者选择适当时机合并代码,同时会将贡献者 的名字添加到项目下的 CONTRIBUTORS 文件。

强制执行的规范

  1. CHANGELOG规范
    1. 项目根目录下需要有一个CHANGELOG文件(通过 git ls-tree HEAD | grep -i changelog |head -n1 检测),建议取名CHANGELOG.md
    2. git push –tags时,对应tag必须出现在changelog文件中 (通过 grep -F -w $tag $changelog_file 来检测)
    3. 建议采用clog 并遵循 angular的commit规范 以便自动生成合理的CHANGELOG文件

附注:已经迁移到 GitHub 的项目:

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.