跳转至

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中无源码包,可上传源码包: ocspkg new-sources setup-x.xx.tar.gz (非必须步骤,按需执行)
  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 参数
      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为例:

  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文件时,请不要修改其他成员的信息。;若团队参与贡献,也可直接联系我们申请仓库权限
  • 如有任何疑问或需要帮助,请随时与我们联系。