re2zero Qtbug Upstream Fixer
Skill Isolation
This skill is fully isolated. Do NOT invoke any other skills (via Skill tool or otherwise) while executing this skill's workflow. This includes but is not limited to: brainstorming, issue-fixer, git-commit-workflow, code-review, feature-dev, test-driven-development, debugging, or any other superpowers/plugin skill.
The only tools allowed are: Bash, Read, Write, Edit, Agent (subagents only), WebFetch, WebSearch, LSP, and TodoWrite. All work must be performed directly within this skill's scripts and workflow — no delegation to external skills.
Workflow for fixing Qt upstream Jira defects and submitting Gerrit patches.
When to Use
Use for:
- Qt Jira issues such as
QTBUG-146018orAUTOSUITE-123. - QTBUG / AUTOSUITE scans from Qt Jira (限定最近两年内的 issue).
- Qt upstream repository fixes intended for
codereview.qt-project.org. - Gerrit submissions using
git review.
Do not use for downstream-only Deepin bugs, Debian CVEs, or general Qt build cleanup.
Core Rules
- Jira API v3: Atlassian 已废弃旧版
GET /searchAPI，必须使用POST /rest/api/3/search/jql（JSON body）。 - SSH 克隆: Gerrit 仓库使用
ssh://USER@codereview.qt-project.org:29418/前缀，而非 HTTPS。 - 时间范围: 默认只扫描最近两年内的 issue（
created >= -2y），避免处理已过时的历史问题。 - During implementation: fix only the reported defect; no refactoring or opportunistic cleanup.
- Follow phases in order: setup → scan → worktree → fix → validate → submit.
- Never run non-dry-run Gerrit submission unless the user explicitly asks to submit.
前置条件 (用户首次使用前必须完成)
⚠️ 缺少配置将无法扫描 Jira 或克隆仓库。请提前完成以下配置。
方式一: 使用配置文件 (推荐)
# 1. 复制配置模板
cp config.env.example config.env
# 2. 编辑配置，填写你的信息
vim config.env
# 3. 运行脚本 (无需手动 source，脚本会自动加载 config.env)
python3 scripts/check_env.py
自动加载机制：所有脚本 (
scan_qtbug.py、workflow.py等) 启动时会自动检测并加载同目录下的config.env，将其中缺失的export变量注入环境变量，因此无需每次手动执行source config.env。若希望全局生效，可将配置写入~/.bashrc。
方式二: 手动设置环境变量 (添加到 ~/.bashrc)
# Jira API 凭据 (必需)
export QTBUG_JIRA_USER="your.email@company.com"
export QTBUG_JIRA_TOKEN="your_atlassian_api_token"
# Gerrit SSH 用户名 (必需, 用于克隆仓库和提交补丁)
export QTBUG_GERRIT_USER="your_username"
# Gerrit SSH Host Key (首次执行一次)
ssh-keyscan -t rsa -p 29418 codereview.qt-project.org >> ~/.ssh/known_hosts
获取 Atlassian API Token: https://id.atlassian.com/manage-profile/security/api-tokens
技能执行流程 (自动)
以下步骤由技能自动完成，用户只需在关键节点确认。
Phase 1: 扫描 Issue
# 扫描最近两年的 Reported issues（默认扫描 QTBUG）
python3 scripts/scan_qtbug.py --limit 20 --format table
# 扫描特定模块（如 Virtual Keyboard）
python3 scripts/scan_qtbug.py --limit 20 --format table
# 查看具体 issue 详情
python3 scripts/scan_qtbug.py --issue QTBUG-146018 --format json
Phase 2: 创建 Worktree 并分析代码
# 克隆仓库（使用 SSH 地址）
git clone --single-branch --branch dev "ssh://USER@codereview.qt-project.org:29418/qt/qtvirtualkeyboard"
# 或通过脚本管理
python3 scripts/qtbug_worktree_manager.py add-repo <ssh-url> --name <cache-name> --single-branch --branch dev
# 创建 issue worktree
python3 scripts/qtbug_worktree_manager.py create <cache-name> QTBUG-146018 --branch dev
Phase 3: 实施修复
cd <worktree>
git add <files>
git commit -m "Fix ..."
git remote rename origin gerrit # git-review 需要此配置
cat > .gitreview << 'EOF'
[gerrit]
host=codereview.qt-project.org
port=29418
project=<project-path>
defaultbranch=dev
EOF
git review # 推送到 Gerrit
技能执行流程详解
详见 references/qtbug-workflow.md，共 6 个阶段：
| 阶段 | 内容 | 自动/手动 |
|---|---|---|
| 0 | 配置 (前置条件) | 手动 — 用户首次使用前完成 |
| 1 | 扫描/选择 Qt upstream issue | 自动 |
| 2 | 克隆仓库并创建 worktree | 自动 |
| 3 | 定位根因并修复代码 | 自动 |
| 4 | 本地验证（构建/测试） | 自动 (可选) |
| 5 | 提交到 Gerrit | 自动 (需用户确认) |
常见问题排查
| 问题 | 解决方法 |
|---|---|
RPC failed / transfer closed |
网络问题，使用 git clone --single-branch 减少传输量 |
Host key verification failed |
运行 ssh-keyscan -t rsa -p 29418 codereview.qt-project.org >> ~/.ssh/known_hosts |
No '.gitreview' file found |
在 worktree 中创建 .gitreview 文件并将远程重命名为 gerrit |
| Jira 返回 0 条记录 | 检查 QTBUG_JIRA_USER / QTBUG_JIRA_TOKEN 环境变量是否正确；Token 是否过期 |
| HTTP 410 Gone | Jira API v3 要求使用 POST /rest/api/3/search/jql 而非 GET |
注意事项
- Worktree 不需要下载全部 Git 历史：使用
--single-branch减少克隆大小 - Gerrit commit-msg hook：脚本会自动安装并 amend commit 添加 Change-Id
- 保持专注：只修复 issue 描述的缺陷，避免"顺便修复"其他问题
- 只修复描述的缺陷：不重构、不做 opportunistic cleanup
热门项目仓库对照表
处理 issue 时，优先选择以下热门项目的缺陷：
| 项目 | Gerrit 仓库路径 | 说明 |
|---|---|---|
| qtbase | qt/qtbase |
Qt 核心框架（widgets、io、network 等） |
| qtdeclarative | qt/qtdeclarative |
QML 和 JavaScript 引擎 |
| qtquick | qt/qtquick |
Qt Quick（QML UI 框架） |
| qtmultimedia | qt/qtmultimedia |
多媒体（音频、视频、相机） |
| qtquick3d | qt/qtquick3d |
3D 渲染 |
| qtsvg | qt/qtsvg |
SVG 图像支持 |
| qtvirtualkeyboard | qt/qtvirtualkeyboard |
虚拟键盘 |
| qtwayland | qt/qtwayland |
Wayland 合成器协议 |
| qtwebengine | qt/qtwebengine |
Chromium 内核浏览器引擎 |
| qtwebsockets | qt/qtwebsockets |
WebSocket 协议 |
| qtwebchannel | qt/qtwebchannel |
WebChannel 通信 |
| qtwebview | qt/qtwebview |
WebView 组件 |
| qtfeedback | qt/qtfeedback |
触觉/音频反馈 |
| qtgamepad | qt/qtgamepad |
游戏手柄支持 |
| qtquickcontrols | qt/qtquickcontrols |
Qt Quick 控件 |
| qtquickcontrols2 | qt/qtquickcontrols2 |
Qt Quick Controls 2 |
| qtnetworkauth | qt/qtnetworkauth |
网络认证（OAuth 等） |
| qtpositioning | qt/qtpositioning |
定位服务 |
| qtsensors | qt/qtsensors |
传感器 API |
| qtserialbus | qt/qtserialbus |
串行总线（CAN、Modbus） |
| qtserialport | qt/qtserialport |
串口通信 |
| qtpim | qt/qtpim |
个人信息管理 |
| qtconnectivity | qt/qtconnectivity |
蓝牙、NFC |
| QtCreator | qt-creator/qt-creator |
Qt Creator IDE |
| QtDesignStudio | qt-creator/QtDesignStudio |
Qt Design Studio |
| qt-apps/neptune3-ui | qt-apps/neptune3-ui |
Neptune 3 车机 UI |
克隆地址格式：
ssh://USER@codereview.qt-project.org:29418/<路径>
选择 Issue 的策略
- 优先热门项目：qtbase、qtdeclarative、qtquick、qtmultimedia、qtvirtualkeyboard 等核心模块影响面广
- description 要具体：选描述清晰、有复现步骤的 issue，避免
tbd或过于模糊的描述 - 检查关联仓库：通过 Jira issue 的
components字段确定目标仓库（如Virtual Keyboard→qt/qtvirtualkeyboard） - 查看评论：检查是否已有相关修复、关联 issue 或更多信息
- 优先简单缺陷：字符串语法错误、简单的空指针检查、边界条件等适合作为入门
- 避免复杂环境依赖：如需要特定硬件、多媒体设备、汽车环境的 issue，优先跳过
- 避开大型重构：description 提到"rewrite"、"architectural change"等通常不适合快速修复