# Qtbug Upstream Fixer

> Use when fixing upstream Qt Jira defects, handling AUTOSUITE-* or QTBUG-* bug reports, preparing Qt Gerrit patches, using git review, or submitting fixes to codereview.qt-project.org.

- Skill: `re2zero/qtbug-upstream-fixer` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add re2zero/qtbug-upstream-fixer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/re2zero/qtbug-upstream-fixer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: re2zero (https://skillmd.com/u/re2zero)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/re2zero/qtbug-upstream-fixer

---


# 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-146018` or `AUTOSUITE-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

1. **Jira API v3**: Atlassian 已废弃旧版 `GET /search` API，必须使用 `POST /rest/api/3/search/jql`（JSON body）。
2. **SSH 克隆**: Gerrit 仓库使用 `ssh://USER@codereview.qt-project.org:29418/` 前缀，而非 HTTPS。
3. **时间范围**: 默认只扫描最近两年内的 issue（`created >= -2y`），避免处理已过时的历史问题。
4. During implementation: fix only the reported defect; no refactoring or opportunistic cleanup.
5. Follow phases in order: setup → scan → worktree → fix → validate → submit.
6. Never run non-dry-run Gerrit submission unless the user explicitly asks to submit.

## 前置条件 (用户首次使用前必须完成)

> ⚠️ 缺少配置将无法扫描 Jira 或克隆仓库。请提前完成以下配置。

**方式一: 使用配置文件 (推荐)**

```bash
# 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)**

```bash
# 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

```bash
# 扫描最近两年的 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 并分析代码

```bash
# 克隆仓库（使用 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: 实施修复

```bash
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 的策略

1. **优先热门项目**：qtbase、qtdeclarative、qtquick、qtmultimedia、qtvirtualkeyboard 等核心模块影响面广
2. **description 要具体**：选描述清晰、有复现步骤的 issue，避免 `tbd` 或过于模糊的描述
3. **检查关联仓库**：通过 Jira issue 的 `components` 字段确定目标仓库（如 `Virtual Keyboard` → `qt/qtvirtualkeyboard`）
4. **查看评论**：检查是否已有相关修复、关联 issue 或更多信息
5. **优先简单缺陷**：字符串语法错误、简单的空指针检查、边界条件等适合作为入门
6. **避免复杂环境依赖**：如需要特定硬件、多媒体设备、汽车环境的 issue，优先跳过
7. **避开大型重构**：description 提到"rewrite"、"architectural change"等通常不适合快速修复