Skip to content

OpenCloudOS Stream 上游版本贡献指南

OpenCloudOS Stream 的所有软件包均记录于：https://gitee.com/OpenCloudOS/rpm_info/blob/master/packages.yaml

该文件以 sig 为单位进行划分，每个 sig 包含 sig 介绍、sig reviewer 和 sig packages。

所有软件包都有且仅有一个所属 sig，同时提供一个 default sig。如果新增软件包不确定应该分类到哪个 sig，则应选择 default sig。

增/删/改仓库

新增仓库、修改仓库 sig/衰退仓库、删除仓库都需要修改 rpm_info/packages.yaml 文件实现，具体操作如下：

  1. fork 仓库：https://gitee.com/OpenCloudOS/rpm_info
  2. clone 仓库：git clone git@gitee.com:<username>/rpm_info.git
  3. 修改 packages.yaml
    • 新增：将新增软件包名添加到合适的 sig-packages 列表尾端
    • 修改：将软件包从一个sig挪到另一个sig，从原先的 sig-packages 列表中删除软件包，添加到新的 sig-packages 列表尾端
    • 衰退：将衰退的软件包移动到 deprecated sig
    • 删除：将软件包名所在行删除
  4. 提交 pull request 并提供修改原因
  5. 流水线判断：是否允许修改并返回评论，若流水线因为网络原因等执行失败，在评论区评论 /retest 可以重新触发流水线
    • 新增：判断是否存在
    • 删除：判断是否属于 deprecated sig
    • 移动：暂时没有相关判断逻辑
  6. 人工审核：是否允许新增、修改仓库 sig、衰退、删除该软件包
  7. 接受 pull request：触发流水线自动执行相应操作：若流水线因为网络原因等执行失败，在评论区评论 /done 可以重新触发流水线
    • 新增：新建仓库，创建README.md，进行初始化设置（设为公开仓库、根据sig设置reviewer、设置允许轻量级pr等）
    • 删除：删除仓库
    • 移动：修改仓库sig label，reviewer

贡献仓库

OpenCloudOS Stream 的所有软件包都存储在 https://gitee.com/opencloudos-stream/ 仓库，以 setup 仓库为例介绍参与贡献流程：

环境配置

  1. 创建所需文件夹：mkdir -p ~/rpmbuild/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS}
  2. 创建mock.cfg：以下提供一个 x86_64 机器上的mock配置，用于本地编译 
    > cat mock.cfg 
# Auto-generated by the Koji build system

config_opts['basedir'] = '/var/lib/mock'
config_opts['chroot_setup_cmd'] = 'groupinstall build'
config_opts['chroothome'] = '/builddir'
config_opts['dnf_warning'] = False
config_opts['package_manager'] = 'dnf'
config_opts['root'] = 'dist-ocs23-build-repo_latest'
config_opts['rpmbuild_networking'] = False
config_opts['rpmbuild_timeout'] = 86400
config_opts['target_arch'] = 'x86_64'
config_opts['use_host_resolv'] = False
config_opts['yum.conf'] = '[main]\ncachedir=/var/cache/yum\ndebuglevel=1\nlogfile=/var/log/yum.log\nreposdir=/dev/null\nretries=20\nobsoletes=1\ngpgcheck=0\nassumeyes=1\nkeepcache=1\ninstall_weak_deps=0\nstrict=1\n\n# repos\n\n[build]\nname=build\nbaseurl=https://build.stream.opencloudos.tech/kojifiles/repos/dist-ocs23-build/latest/x86_64\n'

config_opts['plugin_conf']['ccache_enable'] = False
config_opts['plugin_conf']['root_cache_enable'] = False
config_opts['plugin_conf']['yum_cache_enable'] = False

config_opts['macros']['%_host'] = 'x86_64-koji-linux-gnu'
config_opts['macros']['%_host_cpu'] = 'x86_64'
config_opts['macros']['%_rpmfilename'] = '%%{NAME}-%%{VERSION}-%%{RELEASE}.%%{ARCH}.rpm'
config_opts['macros']['%_topdir'] = '/builddir/build'
config_opts['macros']['%dist'] = '.ocs23'
config_opts['macros']['%distribution'] = 'Koji Testing'
config_opts['macros']['%packager'] = 'Koji'
config_opts['macros']['%vendor'] = 'Koji'

编译流程

以setup仓库为例，编译时参照步骤如下；

方式一：安装ocspkg工具，需要注册账号

  1. 手动 fork setup 仓库到个人仓库：https://gitee.com/opencloudos-stream/setup
  2. 安装并配置ocspkg（配置方式详见：ocspkg-installation.md）
  3. clone setup 仓库：ocspkg clone setup, 然后进入setup仓库：cd setup (ocspkg指令需在仓库中执行)
  4. 对仓库内容进行修改
  5. 获取源码包: ocspkg sources 如果lookaside中无源码包，可上传源码包:(非必须步骤，按需执行): 注：如出现"unauthorized"则为kerberos认证到期, 请执行 kinit续期。
    • ocspkg new-sources setup-x.xx.tar.gz: 上传tarball，清空sources文件后,写入源码包sha值；
    • ocspkg upload setup-x.xx.tar.gz: 上传tarball，在sources文件后,添加源码包sha值；
  6. 编译：
    • 生成src.rpm：ocspkg srpm
    • mock编译：填写/etc/mock/opencloudosstream-$arch.cfg配置文件（$arch视情况替换，如：x86_64），然后执行 ocspkg mockbuild
      • 编译日志：/var/lib/mock/dist-ocs23-build-repo_latest/result
      • 编译结果：/var/lib/mock/dist-ocs23-build-repo_latest/root/builddir/build/
    • koji编译：测试构建请务必使用 scratch 参数 注：如出现"unauthorized"则为kerberos认证到期, 请执行 kinit续期。 
      ocspkg build --scratch --srpm /path/to/xx.src.rpm   # 推荐，使用本地srpm编译
ocspkg build --scratch                              # 从git仓库生成srpm，然后发起编译
  7. 提交代码 
    ocspkg commit -m "input your message"
ocspkg push

方式二：不安装工具，无需注册账号

  1. 手动 fork setup 仓库：https://gitee.com/opencloudos-stream/setup
  2. clone setup 仓库：git clone git@gitee.com:<username>/setup.git
  3. 对仓库内容进行修改
  4. 获取源码包，并创建sources文件
    • 源码包统一存储于 lookaside：https://git.opencloudos.tech/sources-stream/
    • 当前解决方案为将源码包与spec文件内容一同上传至仓库，门禁流水线会自动上传源码包，并提醒开发者检查 sources 文件是否符合要求
    • 通过 sha512sum --tag <tarball_name> 命令获取源码包 sha512 值并写入sources，sources文件需要在末尾保留一个空行，可参考仓库 gcc 的 sources 文件
  5. 将文件移动到rpmbuild目录下：
    • cp * ~/rpmbuild/SOURCES/
    • mv ~/rpmbuild/SOURCES/setup.spec ~/rpmbuild/SPECS/
  6. 生成src.rpm，位于~/rpmbuild/SRPMS目录：rpmbuild -bs ~/rpmbuild/SPECS/setup.spec
  7. 使用mock根据实际生成的src.rpm名进行本地编译：mock -r /path/to/mock.cfg --rebuild ~/rpmbuild/SRPMS/setup-2.13.9.1-4.ocs23.src.rpm
  8. 编译日志及结果
    • 编译日志：/var/lib/mock/dist-ocs23-build-repo_latest/result
    • 编译结果：/var/lib/mock/dist-ocs23-build-repo_latest/root/builddir/build/
  9. 检验结果后将spec文件、源码包以及所需其他文件共同提交pr

CI 门禁

pr 提交后，CI 会进行一系列检查，包括：编译构建测试、安装/卸载测试、安全合规检验

Pull Request 文件检查

为避免开发者误上传源码包到 git 仓库，会检查 pull request 中是否包含压缩文件，如包含则会上传到 lookaside 并返回评论提示开发者删除相关压缩包，也是当前为开发者上传源码包的一种解决方案

编译构建测试

为确保提交软件包质量，提交 pull request 后会触发编译构建测试，根据提交的代码在 x86_64 以及 aarch64 机器上进行编译构建

  • 编译构建测试于koji平台触发：https://build.stream.opencloudos.tech/koji/
  • 编译构建测试测结果由 ocs-bot 评论于对应 pull request

安装/卸载测试

为确保提交软件包能够正常使用，通过编译构建测试后会在 x86_64 以及 aarch64 机器上对生成的二进制软件包依次进行安装卸载测试。

  • 安装/卸载测试结果由 ocs-bot 评论于对应 pull request

安全合规

为了确保项目的安全性和合规性，引入新软件包后我们还会进行以下安全合规相关检查：

  1. 安全漏洞扫描：通过识别可能存在的安全漏洞和弱点，有助于及早发现并解决潜在的安全风险。
  2. 敏感信息扫描：确保不包含敏感信息，如密码、密钥、API 凭证等。保护项目和用户的敏感数据，防止泄露和滥用。
  3. 合规扫描：确保新软件包符合项目所采用的开源协议要求，包括许可证声明和版权信息的正确性。确保项目的合法性和合规性。

通过进行这些扫描和检查，我们可以最大程度地降低引入新软件包可能带来的安全风险，并确保项目的合规性。我们鼓励所有贡献者和团队成员积极参与这些扫描和检查过程，以共同维护项目的安全和合规标准。

升级软件包

stream 版本提供自动升级工具，对于需要升级的软件包，开发者可以在对应仓库下创建升级 issue，一条命令触发自动升级流水线，完成升级以及相关检查。具体流程如下：

  1. 创建升级 issue：默认创建 “升级” 类型 issue，根据模板指引创建 issue，填写升级原因；

  2. 触发升级：评论 /upgrade [version] 可触发指定版本升级；也可评论 /upgrade 使用最新版本升级；

  3. 流水线结果：

    1. 流水线首先返回升级信息，若升级成功则继续触发编译构建及兼容性检查；

    2. 若流水线因网络等偶发原因失败，请评论 /reupgrade 重新触发升级流程；

    3. 若需要修改代码，通过 clone ocs-bot 仓库进行修改：git clone git@gitee.com:ocs-bot/<repo_name>.git，完成修改后评论 /recheck 重新进行编译构建及兼容性检查

  4. 升级结论：兼容性工具检查结果供参考，请根据 Release Note/ Changelog 及代码，分析并确认兼容性，决定是否进行升级

    1. 升级：评论 /pr 即可正式提交 pr

    2. 无需升级：请在侧边栏将状态修改为已拒绝，关闭当前 issue；

    3. 延迟升级：请评论 /TBD [days] 命令挂起本次升级，若不指定挂起天数，会在下次大规模升级时统一触发，若指定天数，则在下次大规模升级时，只有达到该天数才会触发升级；

  5. 帮助命令：评论 /help 可以获得帮助命令输出

注：目前仅支持当前仓库成员执行自动升级流程，申请加入仓库成为仓库成员，请参考 加入仓库 部分。

YUM仓库变更

当前软件包分属在BaseOS, AppStream 和 EPOL 三个YUM仓库中，在版本演进过程中可能会对各仓库中的软件包进行调整，将特定软件包从一个仓库移入另一个仓库（比如从EPOL仓库移入AppStream）。用户需要通过以下步骤申请软件包移仓。

软件包移动通过修改 rpm_info/*.list 文件实现，具体操作如下，以把一个二进制包从EPOL移入AppStream为例：

:warning: 注意：挪到 appstream 的包，要确保其编译依赖、运行依赖在BaseOS、AppStream 闭环，不能依赖 EPOL 内的软件包，同时要 具备独立维护能力 。

  1. fork 仓库：https://gitee.com/OpenCloudOS/rpm_info

  2. clone 仓库：git clone git@gitee.com:<username>/rpm_info.git

  3. 修改epol.list, appstream.list

    • 删除epol.list中需要移出的软件包
    • 将前一步骤中删除的包列表加入appstream.list中

  4. 提交 pull request 并提供变更原因

  5. 人工审核：是否允许移动该软件包

  6. 接受 pull request：触发流水线自动执行YUM源变更操作

  7. 验证。通过 dnf list 查询包是否移动成功

仓库变更 —— 软件包衰退

在衰退软件包时，除了需要在packages.yaml中移动软件包外，还需要将衰退软件包对应的所有二进制软件，从原始列表移到deprecated.list中，并确认没有其他二进制包依赖该衰退软件包。

比如，假设appstream-data这个软件需要衰退，它存在于appstream.list中，那么就需要删除appstream.list中 appstream-data 所有二进制包，添加到 deprecated.list，才算完成 appstream-data 的衰退操作。

加入仓库

我们欢迎并鼓励开发者参与我们的仓库开发，若您想参与社区仓库的维护工作，或体验自动升级流程，您需先申请成为仓库成员。为此，我们通过名为collaborators.yaml的文件将社区开发者添加为仓库成员。

要申请成为仓库开发者，请按照以下步骤操作：

  1. fork 仓库：https://gitee.com/OpenCloudOS/rpm_info
  2. clone 仓库：git clone git@gitee.com:<username>/rpm_info.git
  3. 编辑 collaborators.yaml 文件，添加您的信息。请确保正确填写您的 gitee 账号ID、邮箱和希望加入的仓库名称。
  4. 提交 pull request 并提供修改原因

第一次申请加入仓库时，需要填写 Gitee 账户名称，请以该模板为参考，在 collaborators.yaml 文件末尾追加以下内容： 

- 账号ID: xxx
  仓库:
    - xxx
    - xxx

示例： 

- 账号ID: gitee-bot
  仓库:
    - setup

字段说明：

  • 账号ID：Gitee 账户名称，请务必保证与 gitee 账号ID一致，否则无法正确为您修改权限。以 gitee-bot 用户为例，个人主页中，左上角个人介绍中 @gitee-bot 表示该账号ID为 gitee-bot，与个人空间地址一致，而 Gitee GPG Bot 则是账户昵称，非唯一标识。
  • 仓库：申请加入的仓库列表。

注意事项：

  • 在修改collaborators.yaml文件时，请不要修改其他成员的信息。；若团队参与贡献，也可直接联系我们申请仓库权限
  • 如有任何疑问或需要帮助，请随时与我们联系。