Skip to content

AGENTS.md

Latest commit

 

History

History
104 lines (79 loc) · 5.01 KB

AGENTS.md

File metadata and controls

104 lines (79 loc) · 5.01 KB

AGENTS.md for gui-qml

This file defines how coding agents should work in this repository.

Project intent

  • Repository: gui-qml (Bitcoin Core App QML GUI).
  • Primary focus: Qt/QML GUI code and related build glue.
  • The bitcoin/ directory is a synced submodule from Bitcoin Core. Avoid broad or unrelated edits there.

Scope and boundaries

  • Default in-scope paths:
    • qml/
    • main.cpp
    • top-level CMake files (CMakeLists.txt, cmake/)
    • project docs (README.md, doc/)
  • Treat bitcoin/ as upstream-owned code:
    • Only touch it when explicitly requested by the user.
    • Keep any such edits minimal and tightly justified.

Environment assumptions

  • Required Qt baseline: Qt 6.2.
  • Build system: CMake.
  • Expected binary path after build: build/bin/bitcoin-core-app.

Standard workflow

  1. Sync submodule if needed:
    • git submodule update --init
  2. Configure:
    • cmake -B build
  3. Build:
    • cmake --build build -j$(nproc)
  4. Run:
    • build/bin/bitcoin-core-app

Change quality bar

  • Keep changes focused and minimal for the requested task.
  • Preserve existing code style and naming in touched files.
  • Do not introduce new dependencies unless explicitly asked.
  • Update docs when behavior, commands, or expectations change.

Validation expectations

  • For code changes, at minimum run:
    • cmake --build build -j$(nproc)
  • If tests are added or modified, run relevant tests and report results.
  • If full validation is not possible locally, state what was not run and why.
  • Prefer running validation yourself (build/tests) instead of asking the user to run commands, unless blocked by missing dependencies, permissions, or environment constraints.
  • In the final summary, list the exact validation commands run and whether they passed or failed.
  • For QML test automation changes, run the affected test/functional/qml_test_*.py scripts when available.
  • Exclude generated artifacts from commits while validating (for example test/config.ini, build outputs, and local editor/clangd caches).

Agent execution style

  • When practical, agents should configure/build/run locally and verify behavior end-to-end before claiming a fix.
  • Treat "ready to commit" as requiring a validation check, not only a code review, unless the user explicitly asks for a diff-only answer.

UI and UX guidance

  • Follow repository policies in:
    • doc/icon-policy.md
    • doc/translator-comments.md
  • Keep QML changes responsive and usable on desktop and mobile form factors.
  • Prefer iterative improvements over broad visual rewrites unless requested.

Commit and review hygiene

  • Do not revert unrelated user changes.
  • Keep diffs small and explain notable tradeoffs in the final summary.
  • Prefer small, logically complete commits that represent one validated slice of work (for example: one dependency removal, one test scaffold addition, or one UI behavior change).
  • When a larger issue is in progress, stop at independently buildable/testable checkpoints and commit each checkpoint separately.
  • Avoid mixing unrelated refactors and feature work in the same commit.
  • For pull requests that change the user interface, include screenshots of the updated views in the PR description (cover the affected states/screens).
  • Call out risks, edge cases, and follow-up work when relevant.
  • When creating commits, ensure the commit body contains real paragraph breaks (blank lines), not literal escaped sequences like \n\n.
  • Prefer git commit -m "<subject>" -m "<paragraph1>" -m "<paragraph2>" (one -m per paragraph) or git commit -F <file> for longer messages.

UI automation CLI (for screenshots and manual driving)

  • Prefer test/functional/qml_gui_cli.py for one-off GUI driving, property assertions, and screenshots via the QML test bridge.
  • The CLI can attach to an existing app (--socket-path) or launch a temporary harness-managed app (--launch).
  • Commands return JSON output, which is easier for agents to parse and chain.

Common examples

  1. Launch a temporary app and capture a screenshot:
    • python3 test/functional/qml_gui_cli.py --launch screenshot --output /tmp/gui.png
  2. Launch a temporary app and skip onboarding:
    • python3 test/functional/qml_gui_cli.py --launch --skip-onboard screenshot --output /tmp/gui-wallet.png
  3. Attach to a running app started with -test-automation=/tmp/test_bridge.sock:
    • python3 test/functional/qml_gui_cli.py --socket-path /tmp/test_bridge.sock current-page
    • python3 test/functional/qml_gui_cli.py --socket-path /tmp/test_bridge.sock list-objects --contains send
    • python3 test/functional/qml_gui_cli.py --socket-path /tmp/test_bridge.sock screenshot --output /tmp/send-view.png
  4. Run a scripted sequence from JSON (clicks/waits/screenshot):
    • python3 test/functional/qml_gui_cli.py --socket-path /tmp/test_bridge.sock run-sequence /path/to/sequence.json

Notes

  • The CLI uses the same objectName selectors and test bridge commands as the functional tests.
  • For PR screenshots, capture the affected happy-path and error/edge states when UI behavior changes.