AGENTS.md

Agent guide: pull requests in hiddify-app

PRs go to hiddify/hiddify-app, base main, from a branch pushed to the fork Never open a PR inside the fork.

Before opening

• One feature or fix per PR. Split unrelated changes into separate branches first.
• Branch from the latest upstream/main and rebase right before pushing: git fetch upstream && git rebase upstream/main. git log --oneline upstream/main..HEAD must list only this change's commits.
• Commits follow Conventional Commits: type(scope): summary, e.g. fix(core): …, feat(settings): ….
• Never hide a hiddify-core or hiddify-sing-box bug in the app. No retries, delays, extra ifs, swallowed errors, state guessing, or other workarounds that make a core failure invisible. If the root cause is in the core, say so in the PR (with logs and steps to reproduce), fix it in that repo or open an issue there, and link it. The app may only add handling that is correct regardless of the bug (e.g. showing the error clearly), never logic that papers over it.
• Never commit generated files (*.g.dart, *.freezed.dart, generated translations), core libs, the hiddify-core submodule pointer, build output, recorded videos, keys, or real profile links, IPs or tokens.
• Verified on Android and on a desktop platform. For UI changes, record before/after videos (see below).

Short description (the PR title)

• Conventional Commit style, under 70 characters, imperative, saying what the user gets: fix(home): keep the connect button disabled until the core has stopped.
• Scope is the area touched: home, settings, profile, proxy, core, android, linux, windows, macos, ios, build, ci, …

Full description (the PR body)

Keep it short and complete. Write nothing the reviewer doesn't need.

## Problem
<1–3 sentences on what was wrong or missing, as the user sees it. For bugs, the root cause in one line.>

## Change
- <one bullet per logical change, naming the main file(s)>

## Videos (before | after)
| | English | فارسی |
|---|---|---|
| Mobile light | ![](<m-light-en.webp>) | ![](<m-light-fa.webp>) |
| Mobile dark | ![](<m-dark-en.webp>) | ![](<m-dark-fa.webp>) |
| Desktop light | ![](<d-light-en.webp>) | ![](<d-light-fa.webp>) |
| Desktop dark | ![](<d-dark-en.webp>) | ![](<d-dark-fa.webp>) |

## Tested
- <what was verified, on which platform (Android emulator/device, Linux, Windows, macOS, iOS)>

## Review
- **Confidence:** High (>90%) | Needs review — <one line why>
- **Complexity:** Simple | Complex — <one line why>

• Leave out Videos for changes with no UI effect. For UI changes the section is required, with all 8 views: mobile and desktop × light and dark × English and Persian. Each animated webp shows before | after side by side, both starting at the same moment, with the shorter one holding its last frame.
• Store the videos on the orphan branch e.g., screenshots of the repo you push to (created once with git switch --orphan screenshots), one folder per PR branch, and link their raw URLs in the table:

  wt=$(mktemp -d)
  git fetch origin screenshots 2>/dev/null
  git worktree add $wt origin/screenshots 2>/dev/null || { git worktree add --detach $wt && git -C $wt switch --orphan screenshots; }
  mkdir -p $wt/<branch-slug> && cp <video dir>/*.webp $wt/<branch-slug>/
  git -C $wt add <branch-slug> && git -C $wt commit -m "videos: <branch-slug>" && git -C $wt push origin HEAD:screenshots
  git worktree remove $wt
  # https://raw.githubusercontent.com/<owner>/hiddify-app/screenshots/<branch-slug>/<view>.webp

• Confidence High only when the root cause is understood, the change is local, it was verified on several platforms, and there is no data or migration risk. Otherwise Needs review, saying what to look at.
• Complexity Simple: small, one area, no native code, migration, or API change. Complex: several areas, native code, connection/core logic, DB migrations, or security-relevant code.
• If the change spans repos (e.g. hiddify-core), link the related PR.

Opening

git push -u origin <branch>
gh pr create --repo hiddify/hiddify-app --base main --head <repo>:<branch> \
  --title "<short description>" --body-file <body.md>