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 (limited to issues within the last two years).
• 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 has deprecated the legacy GET /search API; you must use POST /rest/api/3/search/jql（JSON body）。
2. SSH clone: Gerrit repositories use the ssh://USER@codereview.qt-project.org:29418/ prefix, not HTTPS.
3. Time range: By default, only issues within the last two years are scanned (created >= -2y), to avoid processing outdated historical issues.
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.

Prerequisites (must be completed before first use by the user)

⚠️ Without configuration, Jira cannot be scanned and repositories cannot be cloned. Please complete the following configuration in advance.

Option 1: Use a configuration file (recommended)

# 1. 复制配置模板
cp config.env.example config.env

# 2. 编辑配置，填写你的信息
vim config.env

# 3. 运行脚本 (无需手动 source，脚本会自动加载 config.env)
python3 scripts/check_env.py

Automatic loading mechanism: All scripts (scan_qtbug.py、workflow.py , etc.) automatically detect and load config.envin the same directory at startup, injecting the missing export variables into the environment, so there is no need to manually run source config.envevery time. If you want it to take effect globally, you can write the configuration into ~/.bashrc。

Option 2: Manually set environment variables (add to ~/.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

Obtain an Atlassian API Token: https://id.atlassian.com/manage-profile/security/api-tokens

---

Skill execution workflow (automatic)

The following steps are completed automatically by the skill; the user only needs to confirm at key points.

Phase 1: Scan Issues

# 扫描最近两年的 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: Create Worktree and analyze code

# 克隆仓库（使用 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: Implement fixes

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

Skill execution workflow details

See references/qtbug-workflow.md, 6 phases in total:

Phase	Content	Automatic/Manual
0	Configuration (prerequisite)	Manual — completed before first use by the user
1	Scan/select Qt upstream issues	Automatic
2	Clone repository and create worktree	Automatic
3	Locate root cause and fix code	Automatic
4	Local verification (build/test)	Automatic (optional)
5	Submit to Gerrit	Automatic (requires user confirmation)

Common troubleshooting

Issue	Solution
RPC failed / transfer closed	Network issue, use git clone --single-branch to reduce transfer volume
Host key verification failed	Run ssh-keyscan -t rsa -p 29418 codereview.qt-project.org >> ~/.ssh/known_hosts
No '.gitreview' file found	Create .gitreview file in the worktree and rename the remote to gerrit
Jira returns 0 records	Check whether the QTBUG_JIRA_USER / QTBUG_JIRA_TOKEN environment variable is correct; whether the Token has expired
HTTP 410 Gone	Jira API v3 requires the use of POST /rest/api/3/search/jql rather than GET

Notes

• Worktree does not need to download the entire Git history: Use --single-branch to reduce clone size
• Gerrit commit-msg hook: The script automatically installs and amends the commit to add Change-Id
• Stay focused: Only fix the defect described in the issue, avoiding "fixing other issues along the way"
• Only fix the described defect: Do not refactor, do not do opportunistic cleanup

Popular project repository reference table

When handling issues, prioritize defects in the following popular projects:

Project	Gerrit repository path	Description
qtbase	qt/qtbase	Qt core framework (widgets, io, network, etc.)
qtdeclarative	qt/qtdeclarative	QML and JavaScript engine
qtquick	qt/qtquick	Qt Quick (QML UI framework)
qtmultimedia	qt/qtmultimedia	Multimedia (audio, video, camera)
qtquick3d	qt/qtquick3d	3D rendering
qtsvg	qt/qtsvg	SVG image support
qtvirtualkeyboard	qt/qtvirtualkeyboard	Virtual keyboard
qtwayland	qt/qtwayland	Wayland compositor protocol
qtwebengine	qt/qtwebengine	Chromium-based browser engine
qtwebsockets	qt/qtwebsockets	WebSocket protocol
qtwebchannel	qt/qtwebchannel	WebChannel communication
qtwebview	qt/qtwebview	WebView component
qtfeedback	qt/qtfeedback	Haptic/audio feedback
qtgamepad	qt/qtgamepad	Gamepad support
qtquickcontrols	qt/qtquickcontrols	Qt Quick Controls
qtquickcontrols2	qt/qtquickcontrols2	Qt Quick Controls 2
qtnetworkauth	qt/qtnetworkauth	Network authentication (OAuth, etc.)
qtpositioning	qt/qtpositioning	Location services
qtsensors	qt/qtsensors	Sensor API
qtserialbus	qt/qtserialbus	Serial buses (CAN, Modbus)
qtserialport	qt/qtserialport	Serial port communication
qtpim	qt/qtpim	Personal information management
qtconnectivity	qt/qtconnectivity	Bluetooth, 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 automotive UI

Clone URL format：ssh://USER@codereview.qt-project.org:29418/<路径>

Strategy for selecting Issues

1. Prioritize popular projects: core modules such as qtbase, qtdeclarative, qtquick, qtmultimedia, qtvirtualkeyboard, etc. have a broad impact
2. description must be specific: choose issues with clear descriptions and reproduction steps, avoid tbd or overly vague descriptions
3. Check the associated repository: use the Jira issue's components field to determine the target repository (e.g., Virtual Keyboard → qt/qtvirtualkeyboard）
4. Check comments: check whether there is already a related fix, linked issue, or more information
5. Prioritize simple defects: string syntax errors, simple null pointer checks, boundary conditions, etc. are suitable as a starting point
6. Avoid complex environment dependencies: issues that require specific hardware, multimedia devices, or automotive environments should be skipped first
7. Avoid large-scale refactoring: descriptions mentioning "rewrite", "architectural change", etc. are usually not suitable for quick fixes