长期支持版本

    社区创新版本

      patch-tracking

      简介

      在 openEuler 发行版开发过程,需要及时更新上游社区各个软件包的最新代码,修改功能 bug 及安全问题,确保发布的 openEuler 发行版尽可能避免缺陷和漏洞。

      本工具对软件包进行补丁管理,主动监控上游社区提交,自动生成补丁,并自动提交 issue 给对应的 maintainer,同时自动验证补丁基础功能,减少验证工作量支持 maintainer 快速决策。

      架构

      C/S架构

      patch-tracking采用 C/S 架构。

      服务端(patch-tracking) :负责执行补丁跟踪任务,包括:维护跟踪项,识别上游仓库分支代码变更并形成补丁文件,向 Gitee 提交 issue 及 PR,同时 patch-tracking 提供 RESTful 接口,用于对跟踪项进行增删改查操作。

      客户端:即命令行工具(patch-tracking-cli),通过调用 patch-tracking 的 RESTful 接口,实现对跟踪项的增删改查操作。

      核心流程

      1, 补丁跟踪服务流程

      主要步骤:

      1. 通过命令行工具添加跟踪项。
      2. 自动从跟踪项配置的上游仓库(例如GitHub)获取补丁文件。
      3. 创建临时分支,将获取到的补丁文件提交到临时分支。
      4. 自动提交 issue 到对应仓库,并生成关联 issue 的 PR。

      PatchTracking

      2, Maintainer对提交的补丁处理流程

      主要步骤:

      1. Maintainer 分析 PR。
      2. 执行 CI,执行成功后判断是否合入 PR。

      Maintainer

      数据结构

      • Tracking表
      序号名称说明类型允许空
      1id自增补丁跟踪项序号int-NO
      2version_control上游SCM的版本控制系统类型String-NO
      3scm_repo上游SCM仓库地址String-NO
      4scm_branch上游SCM跟踪分支String-NO
      5scm_commit上游代码最新处理过的Commit IDString-YES
      6repo包源码在Gitee的仓库地址StringPrimaryNO
      7branch包源码在Gitee的仓库分支StringPrimaryNO
      8enabled是否启动跟踪Boolean-NO
      • Issue表
      序号名称说明类型允许空
      1issueissue编号StringPrimaryNO
      2repo包源码在Gitee的仓库地址String-NO
      3branch包源码在Gitee的仓库分支String-NO

      工具部署

      软件下载

      Repo 源地址:https://repo.openeuler.org/

      rpm 包获取地址:https://build.openeuler.org/package/show/openEuler:21.03/patch-tracking

      安装工具

      方法1:从repo源安装

      1. 使用 dnf 挂载 repo源(需要 22.03-LTS-SP1 或更新的 repo 源,具体方法参考应用开发指南),然后执行如下指令下载以及安装 patch-tracking 及其依赖。

      2. 执行以下命令安装patch-tracking

        dnf install patch-tracking
        

      方法2:直接使用rpm安装

      1. 首先安装相关依赖。

        dnf install python3-uWSGI python3-flask python3-Flask-SQLAlchemy python3-Flask-APScheduler python3-Flask-HTTPAuth python3-requests python3-pandas
        
      2. patch-tracking-1.0.0-1.oe1.noarch.rpm为例,执行如下命令安装。

        rpm -ivh patch-tracking-1.0.0-1.oe1.noarch.rpm
        

      生成证书

      执行如下命令生成证书。

      openssl req -x509 -days 3650 -subj "/CN=self-signed" \
      -nodes -newkey rsa:4096 -keyout self-signed.key -out self-signed.crt
      

      将生成的 self-signed.keyself-signed.crt 文件拷贝到 /etc/patch-tracking 目录。

      配置参数

      在配置文件中对相应参数进行配置,配置文件路径为 /etc/patch-tracking/settings.conf

      1. 配置服务监听地址。

        LISTEN = "127.0.0.1:5001"
        
      2. GitHub Token, 用于访问托管在 GitHub 上游开源软件仓的仓库信息 , 生成 GitHub Token 的方法参考 Creating a personal access token

        GITHUB_ACCESS_TOKEN = ""
        
      3. 对于托管在gitee上的需要跟踪的仓库,配置一个有该仓库权限的gitee的token,用于提交patch文件,提交issue,提交PR等操作。

        GITEE_ACCESS_TOKEN = ""
        
      4. 定时扫描数据库中是否有新增或修改的跟踪项,对扫描到的跟踪项执行获取上游补丁任务,在这里配置扫描的时间间隔,数字单位是秒。

        SCAN_DB_INTERVAL = 3600
        
      5. 命令行工具运行过程中,POST接口需要填写进行认证的用户名和口令哈希值。

        USER = "admin"
        
        PASSWORD = ""
        

      说明:
      USER默认值为admin

      ​ 执行如下指令,获取口令的哈希值,其中Test@123为设置的口令。

      [root]# generate_password Test@123
      pbkdf2:sha256:150000$w38eLeRm$ebb5069ba3b4dda39a698bd1d9d7f5f848af3bd93b11e0cde2b28e9e34bfbbae
      

      说明:

      口令值需要满足如下复杂度要求:

      • 长度大于等于6个字符
      • 必须包含大写字母、小写字母、数字、特殊字符(~!@#%^*-_=+)

      将口令的哈希值pbkdf2:sha256:150000$w38eLeRm$ebb5069ba3b4dda39a698bd1d9d7f5f848af3bd93b11e0cde2b28e9e34bfbbae配置到PASSWORD = ""引号中。

      启动补丁跟踪服务

      可以使用以下两种方式启动服务。

      • 使用systemd方式。

        systemctl start patch-tracking
        
      • 直接执行可执行程序。

        /usr/bin/patch-tracking
        

      工具使用

      1,添加跟踪项

      将需要跟踪的软件仓库和分支与其上游开源软件仓库与分支关联起来,可以通过以下三种方式实现。

      • 命令行直接添加

      参数含义:

      --user :POST接口需要进行认证的用户名,同settings.conf中的USER参数
      --password :POST接口需要进行认证的口令,为settings.conf中的PASSWORD哈希值对应的实际的口令字符串
      --server :启动Patch Tracking服务的URL,例如:127.0.0.1:5001
      --version_control :上游仓库版本的控制工具,只支持github
      --repo: 需要进行跟踪的仓库名称,格式:组织/仓库
      --branch :需要进行跟踪的仓库的分支名称
      --scm_repo :被跟踪的上游仓库的仓库名称,github格式:组织/仓库
      --scm_branch: 被跟踪的上游仓库的仓库的分支
      --enabled :是否自动跟踪该仓库

      例如:

      patch-tracking-cli add --server 127.0.0.1:5001 --user admin --password Test@123 --version_control github --repo testPatchTrack/testPatch1 --branch master --scm_repo BJMX/testPatch01 --scm_branch test  --enabled true
      
      • 指定文件添加

      参数含义:

      --server :启动Patch Tracking服务的URL,例如:127.0.0.1:5001
      --user :POST接口需要进行认证的用户名,同settings.conf中的USER参数
      --password :POST接口需要进行认证的口令,为settings.conf中的PASSWORD哈希值对应的实际的口令字符串
      --file :yaml文件路径

      将仓库、分支、版本管理工具、是否启动监控等信息写入yaml文件(例如tracking.yaml),文件路径作为--file的入参调用命令。

      例如:

      patch-tracking-cli add --server 127.0.0.1:5001 --user admin --password Test@123 --file tracking.yaml
      

      yaml文件内容格式如下,冒号左边的内容不可修改,右边内容根据实际情况填写。

      version_control: github
      scm_repo: xxx/xxx
      scm_branch: master
      repo: xxx/xxx
      branch: master
      enabled: true
      

      version_control :上游仓库版本的控制工具,只支持github
      scm_repo :被跟踪的上游仓库的仓库名称,github格式:组织/仓库
      scm_branch :被跟踪的上游仓库的仓库的分支
      repo :需要进行跟踪的仓库名称,格式:组织/仓库
      branch :需要进行跟踪的仓库的分支名称
      enabled :是否自动跟踪该仓库

      • 指定目录添加

      在指定的目录,例如test_yaml下放入多个xxx.yaml文件,执行如下命令,记录指定目录下所有yaml文件的跟踪项。

      参数含义:

      --user :POST接口需要进行认证的用户名,同settings.conf中的USER参数
      --password :POST接口需要进行认证的口令,为settings.conf中的PASSWORD哈希值对应的实际的口令字符串
      --server :启动Patch Tracking服务的URL,例如:127.0.0.1:5001
      --dir :存放yaml文件目录的路径

      patch-tracking-cli add --server 127.0.0.1:5001 --user admin --password Test@123 --dir /home/Work/test_yaml/
      

      2, 查询跟踪项

      参数含义:

      --server :必选参数,启动Patch Tracking服务的URL,例如:127.0.0.1:5001
      --table :必选参数,需要查询的表
      --repo :可选参数,需要查询的repo;如果没有该参数查询表中所有内容
      --branch :可选参数,需要查询的branch

      patch-tracking-cli query --server SERVER --table tracking
      

      例如:

      patch-tracking-cli query --server 127.0.0.1:5001 --table tracking
      

      3, 查询生成的 Issue

      patch-tracking-cli query --server SERVER --table issue
      

      例如:

      patch-tracking-cli query --server 127.0.0.1:5001 --table issue
      

      4, 删除跟踪项

      patch-tracking-cli delete --server SERVER --user USER --password PWD --repo REPO [--branch BRANCH]
      

      例如:

      patch-tracking-cli delete --server 127.0.0.1:5001 --user admin --password Test@123 --repo testPatchTrack/testPatch1 --branch master
      

      说明:

      可以删除指定repo和branch的单条数据;也可直接删除指定repo下所有branch的数据。

      5, 码云查看 issue 及 PR

      登录Gitee上进行跟踪的软件项目,在该项目的Issues和Pull Requests页签下,可以查看到名为[patch tracking] TIME,例如 [patch tracking] 20200713101548的条目,该条目即是刚生成的补丁文件的issue和对应PR。

      FAQ

      访问 api.github.com Connection refused 异常

      问题描述

      patch-tracking 运行过程中,可能会出现如下报错:

       9月 21 22:00:10 localhost.localdomain patch-tracking[36358]: 2020-09-21 22:00:10,812 - patch_tracking.util.github_api - WARNING - HTTPSConnectionPool(host='api.github.com', port=443): Max retries exceeded with url: /user (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0xfffe19d35820>: Failed to establish a new connection: [Errno 111] Connection refused'))   
      

      原因分析

      以上问题是 patch-tracking 与 GitHub API 服务之间网络访问不稳定导致,请确保在与 GitHub API 服务之间网络稳定的环境中(如华为云任一国际站点)运行 patch-tracking。

      文档捉虫

      “有虫”文档片段

      问题描述

      提交类型 issue

      有点复杂...

      找人问问吧。

      PR

      小问题,全程线上修改...

      一键搞定!

      问题类型
      规范和低错类

      ● 错别字或拼写错误;标点符号使用错误;

      ● 链接错误、空单元格、格式错误;

      ● 英文中包含中文字符;

      ● 界面和描述不一致,但不影响操作;

      ● 表述不通顺,但不影响理解;

      ● 版本号不匹配:如软件包名称、界面版本号;

      易用性

      ● 关键步骤错误或缺失,无法指导用户完成任务;

      ● 缺少必要的前提条件、注意事项等;

      ● 图形、表格、文字等晦涩难懂;

      ● 逻辑不清晰,该分类、分项、分步骤的没有给出;

      正确性

      ● 技术原理、功能、规格等描述和软件不一致,存在错误;

      ● 原理图、架构图等存在错误;

      ● 命令、命令参数等错误;

      ● 代码片段错误;

      ● 命令无法完成对应功能;

      ● 界面错误,无法指导操作;

      风险提示

      ● 对重要数据或系统存在风险的操作,缺少安全提示;

      内容合规

      ● 违反法律法规,涉及政治、领土主权等敏感词;

      ● 内容侵权;

      您对文档的总体满意度

      非常不满意
      非常满意
      提交
      根据您的反馈,会自动生成issue模板。您只需点击按钮,创建issue即可。
      文档捉虫
      编组 3备份