AGENTS.md

1# Agent Contribution Guidelines
2 
3Language: English | [简体中文](AGENTS-ZH.md)
4 
5This document defines the rules for AI agents (and the humans operating them)
6working on this repository — whether you are contributing a pull request or
7assisting a maintainer locally. It supplements, and never overrides,
8[CONTRIBUTING.md](CONTRIBUTING.md) and the
9[Compatibility Policy](COMPATIBILITY_POLICY.md).
10 
11dio is one of the most depended-on packages in the Dart/Flutter ecosystem.
12A single careless change can break tens of thousands of downstream projects.
13Contributions here are not a playground: every change must be motivated,
14tested, and compatible.
15 
16## 1. Motivation first — no speculative changes
17 
18**Do not invent work.** A change is only acceptable when it solves a problem
19that actually exists.
20 
21- Every non-trivial change must be traceable to a concrete motivation:
22  a reproducible bug, an accepted issue/discussion, an RFC-style proposal,
23  or an explicit maintainer request. "This seems useful" is not a motivation.
24- Before implementing a feature, answer these questions in the issue or the
25  PR description — if you cannot, do not open the PR:
26  1. What cannot be done (or is done poorly) with the current dio?
27  2. Who needs this, and in which real-world scenario?
28  3. Why does it belong in dio itself, instead of an interceptor, an adapter,
29     a transformer, or a separate package? dio is intentionally extensible;
30     most needs are served by its extension points without core changes.
31  4. What is the cost — API surface, maintenance burden, compatibility risk?
32- One PR, one concern. Do not bundle several unrelated features or fixes
33  into a single PR. Bundled "improvement packs" might be closed unreviewed.
34- For any user-facing feature, open an issue for discussion **before**
35  writing code, unless a maintainer has already asked for it. A bare
36  `Closes #NNNN` is not the same as prior discussion: the referenced issue
37  must show that maintainers have expressed interest or accepted the
38  direction. Feature PRs without that grounding waste both your tokens and
39  the maintainers' time, and might be closed.
40 
41## 2. Tests are mandatory for logic changes
42 
43Every behavioral change must be proven by tests.
44 
45- Any change to logic requires new tests or adjustments to existing tests
46  that fail without the change and pass with it. Bug fixes must include a
47  regression test that reproduces the original report.
48- CI reports coverage diffs on every PR. The published minimum threshold is
49  low, but that is a floor, not a target: coverage of code you changed
50  should not regress, and new logic (including error paths) should be
51  covered by real assertions.
52- Tests must be **effective and non-duplicated**:
53  - Assert observable behavior, not implementation details.
54  - Do not add tests that merely re-execute existing covered paths to
55    inflate coverage numbers.
56  - Search the existing suites first — extend an existing test group
57    instead of creating a near-duplicate file.
58- Put tests in the right place:
59  - Package-specific behavior → `<package>/test/`.
60  - Behavior that must hold across all adapters/platforms → the shared
61    `dio_test` package.
62- Run the checks locally before claiming they pass:
63 
64```bash
65  melos run format   # or format:fix
66  melos run analyze
67  melos run test     # or targeted: test:vm / test:web / test:flutter
68```
69 
70- Never state that tests pass without having run them. Never check a PR
71  checklist item you have not actually done. Misreporting verification
72  status may lead to the PR being closed.
73 
74## 3. Compatibility is sacred — avoid breaking changes
75 
76dio's public API is a contract with an enormous downstream. Treat every
77public symbol as frozen unless a maintainer decides otherwise.
78 
79- **Default to non-breaking.** Prefer additive changes: new optional named
80  parameters with safe defaults, new classes, new extension points.
81- Do not change public method signatures, remove/rename public symbols,
82  change default behavior, or alter thrown exception types without going
83  through a deprecation cycle. Breaking changes belong in major releases.
84  As dio's own [CHANGELOG](dio/CHANGELOG.md) preamble states, unavoidable
85  breaking changes may occasionally ship in minor releases — those still
86  require maintainer sign-off in advance and an entry in the
87  [Migration Guide](dio/doc/migration_guide.md).
88- If an API must go away, deprecate first and keep it working:
89 
90```dart
91  @Deprecated('Use XXX instead. This will be removed in X.0.0')
92```
93 
94  Deprecations must state their replacement and the removal version, and
95  are only removed in the next major release, together with an entry in
96  the Migration Guide. Target the *next* major, not a version beyond that.
97- Do not raise the minimum Dart/Flutter SDK constraint of any package
98  unless required by the [Compatibility Policy](COMPATIBILITY_POLICY.md)
99  or its listed exceptions. CI tests against the minimum supported SDK;
100  do not use language/library features beyond a package's lower bound.
101- Watch for **behavioral** breaking changes too: changing defaults, header
102  normalization, redirect/error semantics, or timing/ordering of
103  interceptors can break downstream even when signatures are untouched.
104- If a breaking change is genuinely unavoidable, stop and raise it in an
105  issue for maintainers to decide. Do not merge-request it unilaterally.
106 
107### Extra scrutiny in security- and network-critical areas
108 
109Some parts of dio have oversized blast radius when broken. Changes here
110require extra care, and the PR description should explicitly call the
111change out and @-mention a maintainer:
112 
113- SSL / TLS handling and certificate pinning (`badCertificateCallback`,
114  `SecurityContext`, adapters' `HttpClient` configuration).
115- Redirect handling and cross-origin behavior (redirect policy, header
116  forwarding, cookie leakage across redirects).
117- Cookie management (`dio_cookie_manager`, domain / path matching).
118- Header handling (`Authorization`, `Content-Type`, casing, duplicates).
119- Timeout, cancellation, and connection pooling.
120- The interceptor pipeline (ordering, error propagation, `next` /
121  `resolve` / `reject` semantics).
122- Request-body encoding: `FormData`, multipart streaming, encoding
123  detection.
124 
125Rule of thumb: if getting this wrong could leak credentials, hang a
126request forever, or change data on the wire, treat it as sensitive.
127 
128### Test certificates and keys
129 
130Self-signed certificates and their private keys used only for local
131test fixtures (TLS, ALPN, pinning, etc.) are **not real secrets** — but
132committing static `.key`/`.crt` files still has costs: secret-scanner
133noise, package-size bloat for published artifacts, and inconsistency
134with this repo's convention of generating such fixtures at test time
135(see `scripts/prepare_pinning_certs.sh`).
136 
137- **Prefer generating certificates at test setup** (via `openssl` in
138  a `setUp`/helper, or a setup script) over committing static files.
139- **If a static fixture is unavoidable**, exclude it from the published
140  package with both:
141  - `false_secrets` in the package's `pubspec.yaml` (suppresses pub's
142    leak-detection warning), and
143  - a `.pubignore` **inside the fixture subdirectory** (e.g.
144    `test/certificates/.pubignore`), never at the package root — a
145    root-level `.pubignore` overrides the root `.gitignore` for the
146    entire directory, silently re-including build artifacts and other
147    git-ignored files in the published package.
148 
149### Dependency changes
150 
151Do not bundle drive-by dependency bumps into a feature/fix PR. When a
152dependency change is itself the point of the PR:
153 
154- State the reason in the description (security fix, required for a new
155  feature, upstream deprecation, etc.). "Latest is greater" is not a
156  reason.
157- Verify the change under every supported SDK version declared in the
158  affected `pubspec.yaml`. Do not raise the package's SDK lower bound
159  just to accommodate the new dependency unless the
160  [Compatibility Policy](COMPATIBILITY_POLICY.md) allows it.
161- Prefer the narrowest constraint that solves the problem (patch >
162  minor > major bump).
163- Call out any new transitive dependencies — downstream users care about
164  their lockfile.
165- Use `⬆️ chore` (or `chore(deps)`) as the commit type.
166 
167## 4. Understand before you change
168 
169- Read the surrounding code and existing patterns before editing. Match
170  the existing style, naming, and module boundaries.
171- Fix root causes, not symptoms. When a symptom is reported, locate the
172  actual defect before patching.
173- Never guess an API — neither dio's internals nor third-party packages.
174  Read the actual source and the package's own tests/examples when
175  unsure. If `dart analyze` says a member does not exist, go back to the
176  source instead of retrying variations. Dependency source locations:
177 
178  | Platform | Default location |
179  |---|---|
180  | macOS / Linux | `~/.pub-cache/hosted/pub.dev/<package>-<version>/` |
181  | Windows | `%LOCALAPPDATA%\Pub\Cache\hosted\pub.dev\<package>-<version>\` |
182 
183  If the `PUB_CACHE` environment variable is set, use that location
184  instead of the platform default.
185- **Verify every external fact before writing it down.** Agents
186  routinely hallucinate numbers and attach wrong labels to them — RFC
187  numbers, issue/PR numbers, library/API version numbers, CVE
188  identifiers, deprecation timelines, benchmark figures, attributed
189  quotes, platform-behavior claims ("iOS X.Y and later…"). A wrong
190  citation in a commit message, changelog, or doc comment is worse
191  than no citation, because it misleads downstream readers and
192  reviewers who trust it. Before writing any external fact:
193  1. Look up the source and confirm it says what you claim. For RFCs,
194     check `https://www.rfc-editor.org/rfc/rfcNNNN` (or
195     `https://datatracker.ietf.org/doc/rfcNNNN/`) and confirm the
196     title matches; for issues/PRs, open the link; for library
197     versions, read the package's own changelog/source.
198  2. Confirm any section anchor, version number, or quoted text you
199     cite actually exists at that source.
200  3. If you cannot verify the fact online, drop the citation and
201     describe the observed behavior in your own words instead. Do not
202     guess a number to make a statement look authoritative.
203  This applies to commit messages, `CHANGELOG.md`, doc comments,
204  README, and any prose in a PR description.
205 
206## 5. Production quality only
207 
208- No placeholder work: no `TODO`/`FIXME` left behind, no mocked or
209  simplified logic presented as complete, no "will optimize later" code.
210- Handle edge cases and error paths explicitly; never swallow errors
211  silently.
212- If you cannot finish something completely, say so explicitly and state
213  the boundary — do not pretend it is done.
214 
215## 6. When to stop and ask
216 
217Agents default to "guess and proceed". Do not. Pause and check with the
218operator (or open a discussion issue) when:
219 
220- The task description is ambiguous and multiple reasonable interpretations
221  would produce materially different implementations.
222- Fixing the reported problem would require design changes that go beyond
223  what was asked for.
224- The right fix touches an area not obviously in scope (e.g., renaming a
225  public API to fix an unrelated bug, or restructuring an interceptor
226  pipeline to enable a small feature).
227- You cannot reproduce the reported issue after a reasonable attempt.
228- The request itself seems wrong (e.g., the "bug" is intended behavior, or
229  the "feature" would violate a rule in this document).
230 
231Do **not** stop to ask permission for routine mechanical steps: running
232tests / format / analyze, staging files, opening a draft PR, or choices
233that are already decided by this document (commit format, changelog,
234attribution).
235 
236## 7. Repository layout
237 
238This is a [Melos](https://github.com/invertase/melos/tree/main/docs)
239mono-repo:
240 
241| Path | Package |
242|---|---|
243| `dio/` | The core package |
244| `plugins/web_adapter/` | `dio_web_adapter` |
245| `plugins/cookie_manager/` | `dio_cookie_manager` |
246| `plugins/http2_adapter/` | `dio_http2_adapter` |
247| `plugins/native_dio_adapter/` | `native_dio_adapter` |
248| `plugins/compatibility_layer/` | `dio_compatibility_layer` |
249| `dio_test/` | Shared test suites for all adapters |
250| `example_dart/`, `example_flutter_app/` | Examples |
251 
252Setup:
253 
254```bash
255dart pub global activate melos
256melos bootstrap
257```
258 
259Each package versions and releases independently. Note that packages have
260**different SDK lower bounds** (see each `pubspec.yaml`).
261 
262## 8. Commits, changelog, and PR hygiene
263 
264### 8.1 Branch naming
265 
266Work on a feature branch named `category/ticket-id-or-short-description`:
267 
268- `category` matches the Conventional type used in the commit:
269  `feat`, `fix`, `perf`, `refactor`, `docs`, `test`, `chore`, `ci`,
270  `style`.
271- Use the tracked **ticket id** when one exists — the issue or PR
272  number: `fix/2201`, `feat/2555`. Combining both is fine when it aids
273  discoverability: `fix/2201-cookie-domain-match`.
274- Otherwise use a **short description** — 2–5 kebab-case words that
275  describe the change (`docs/agents-guidelines`,
276  `feat/cors-preflight-warning`, `chore/bump-http2-3.0.0`).
277 
278Rules:
279 
280- Never work on `main` directly.
281- One branch per PR; do not reuse a merged branch for a new change.
282- Keep branch names ASCII, lowercase, and short.
283 
284### 8.2 Commit message format — Gitmoji or Conventional
285 
286Every commit uses **[gitmoji](https://gitmoji.dev)** at the front or a
287**[Conventional Commits](https://www.conventionalcommits.org)** type
288prefix. Emojis are chosen from the gitmoji specification — do not invent
289new ones.
290 
291```
292<gitmoji> <Short imperative subject>
293(or)
294<type>[(<scope>)]: <short imperative subject>
295 
296[optional body — wrap at ~72 chars]
297 
298[optional footer, e.g. Closes #1234]
299```
300 
301Gitmoji commonly used in this repository (see `git log` for the full set).
302**Pick one column — never both.** Each row maps a gitmoji to its
303equivalent Conventional-type prefix; you use the emoji **or** the type,
304not the two glued together. `🔧 chore: ...` is wrong.
305 
306| Gitmoji | Conventional type | Use for |
307|---|---|---|
308| ✨ `:sparkles:` | `feat` | New user-facing feature |
309| 🐛 `:bug:` | `fix` | Bug fix |
310| ⚡️ `:zap:` | `perf` | Performance improvement |
311| ♻️ `:recycle:` | `refactor` | Refactor with no behavior change |
312| 📝 `:memo:` | `docs` | Documentation |
313| ✅ `:white_check_mark:` | `test` | Tests only |
314| 🚨 `:rotating_light:` | `fix` / `style` | Fix linter or analyzer warnings |
315| 🥅 `:goal_net:` | `fix` / `refactor` | Catch errors / improve error handling |
316| 🔧 `:wrench:` | `chore` | Config / tooling |
317| 👷 `:construction_worker:` | `ci` | CI / workflow changes |
318| 💚 `:green_heart:` | `ci` | Fix a failing CI job |
319| ⬆️ `:arrow_up:` | `chore` | Bump a dependency |
320| 🔥 `:fire:` | `chore` / `refactor` | Remove code or files |
321| 🎨 `:art:` | `style` | Formatting / structure only |
322| 🔖 `:bookmark:` | `chore(release)` | Release (**maintainers only**) |
323 
324Rules:
325 
326- Subject is an imperative English sentence. Do not append the PR number —
327  GitHub adds `(#N)` automatically on squash-merge.
328- Use scope when it clarifies (`fix(dio_web_adapter): ...`); omit when it
329  would just repeat the file path.
330- Position 0 is either the emoji or the Conventional prefix plus colon, then a space, then the subject.
331- After a gitmoji the subject starts with a **capital letter**
332  (`🐛 Allow ...`, `📝 Clarify ...`); after a Conventional prefix the
333  subject stays lowercase (`docs: add ...`, `perf(dio): reduce ...`).
334 
335Examples (adapted from actual repo history):
336 
337```
338🐛 Allow `callFollowingErrorInterceptor` when rejecting in `ErrorInterceptorHandler`
339perf(dio): reduce `FormData.readAsBytes` memory usage for large payloads
340docs: add agent contribution guidelines
341```
342 
343Do **not** combine the two styles:
344 
345```
346❌ 🔧 chore: group codeql-action updates      (both gitmoji AND prefix)
347✅ 🔧 Group codeql-action updates              (gitmoji only, capitalized subject)
348✅ chore: group codeql-action updates          (Conventional only, lowercase subject)
349```
350 
351### 8.3 AI attribution — mandatory
352 
353Transparency about AI involvement is required. Do not hide it, and do not
354skip it "to keep the commit clean".
355 
356- Add a `Co-Authored-By:` trailer for **every AI agent** that produced
357  code, tests, or docs in the commit:
358 
359```
360  Co-Authored-By: Claude <noreply@anthropic.com>
361  Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
362```
363 
364  Use the identity the agent itself publishes (see its own docs / recent
365  commits from that agent on GitHub). Multiple agents → multiple trailers.
366- Also disclose in the PR description **which agent(s) were used and for
367  what stage** — design, implementation, tests, or review. One line is
368  enough, e.g.:
369 
370  > *Implementation and tests by Devin; local review pass by GLM-5.2.*
371 
372- AI attribution never shifts accountability. The human submitting the PR
373  owns every line, must understand it, and must respond to review feedback
374  substantively. "The AI wrote it" is not an answer to a review question.
375 
376### 8.4 CHANGELOG and docs
377 
378- Update the `CHANGELOG.md` of **every package you changed**, under
379  `## Unreleased` (replace `*None.*`).
380- One concise bullet per change, written for downstream users, not for
381  reviewers.
382- Do not bump version numbers — releases are handled by maintainers.
383- When public APIs change, also update `README.md`, `README-ZH.md`, API
384  doc comments, and any affected examples.
385 
386### 8.5 Self-review your diff before every commit
387 
388Always inspect what you are about to commit:
389 
390```bash
391git diff                          # unstaged
392git diff --staged                 # staged
393git diff &lt;base-branch&gt;...HEAD     # full branch diff before opening/updating a PR
394```
395 
396Remove before committing:
397 
398- Debug output (`print`, `debugPrint`, `console.log`, temporary logs).
399- Commented-out code left from earlier attempts.
400- Reformatting or import re-ordering of files that are not the subject
401  of this change.
402- Unrelated bumps in `pubspec.yaml` / `pubspec.lock`.
403- Whitespace-only changes in unrelated files.
404- Editor/OS junk (`.DS_Store`, `.idea/`, personal scratch files).
405 
406If you cannot explain why a hunk is in the diff, it does not belong in
407the commit. Never use `git add .` or `git add -A` — stage files by path.
408 
409**Also re-read the commit message against the staged diff.** A message
410carried over from a previous attempt, or auto-completed from an
411unrelated commit, is easy to miss and lands verbatim in history. If the
412message and the diff describe different work, one of them is wrong.
413 
414### 8.6 Opening the PR
415 
416- **Open as a draft PR** (`Create draft pull request`) when the change
417  is large, exploratory, or when you want maintainer direction before
418  polishing. Convert to Ready for Review once local checks pass and the
419  description is complete.
420- Reference the closing issue with `Closes #NNNN` in the description.
421- Follow the AI attribution rules in §8.3: disclose which agent(s)
422  contributed and at which stage.
423- Write PR titles and bodies in English, in the same commit style as
424  §8.2.
425- Only tick a PR checklist item that is genuinely done. For items that
426  do not apply, keep the box unchecked and add *(not applicable —
427  reason)* next to it. Do not check "done" as a shortcut.
428- **Describe verification honestly — no boilerplate "Test plan"
429  checklist.** In prose, state what you actually confirmed and how, in
430  one or two sentences:
431 
432  > *Added 15 unit tests covering method / content-type / custom-header
433  > combinations; `melos run test:vm` and `melos run analyze` clean.*
434 
435  Do **not** paste a generic checklist — this is the anti-pattern this
436  section is explicitly rejecting, even if your agent tooling suggests
437  one by default:
438 
439```
440  ❌  ## Test plan
441      - [ ] Tests pass
442      - [ ] Feature works as expected
443```
444 
445  Mechanical prerequisites (`dart analyze`, `dart format`) are already
446  covered by the PR template's top-level checklist — do not re-list them
447  as "tests". Behavioral verification means checks that would fail if
448  this change regressed.
449 
450  If something that ought to be verified genuinely could not be — needs
451  browser CI, a physical device, production load, and so on — list it
452  under a short **Unverified** paragraph explaining why. Unverified
453  items are known risks; this should stay rare, not become routine.
454 
455### 8.7 Review iteration workflow
456 
457After opening the PR:
458 
459- **Address feedback with new commits appended to the branch**, not by
460  squash-and-force-push. Maintainers rely on incremental history during
461  review; squashing happens at merge time.
462- **Avoid `git push --force` on a branch that already has review
463  comments** — it detaches those comments from their code position. If a
464  rebase is genuinely required (e.g., conflict resolution against
465  `main`), leave a comment before pushing so reviewers know.
466- **Do not close and reopen the PR** to reset review state, retry CI, or
467  bypass a blocking review. Push a fix instead.
468- **Design-level feedback is a conversation, not an instruction.** If a
469  reviewer's suggestion changes the intent of the PR (not just its
470  implementation), reply first and reach agreement before writing new
471  code. Blindly applying a large suggestion is worse than discussing it.
472- **Mark review threads resolved** only after you have addressed the
473  point in code and left a reply explaining what changed — or after the
474  reviewer explicitly says so. Do not silently resolve.
475- **CI failures**: read the failing job's log, find the root cause, then
476  push a fix. Never re-run CI hoping for a green run. If a test is
477  genuinely flaky, say so in a comment — do not paper over it by
478  disabling the test or adding retries.
479 
480## 9. Patterns that may lead to closure
481 
482Quick cross-reference — each pattern is a violation of the rules above.
483PRs matching one or more of these may be closed without detailed review
484at the maintainers' discretion.
485 
486| Pattern | See |
487|---|---|
488| No motivation or prior maintainer discussion | §1 |
489| Multiple unrelated changes bundled in one PR | §1 |
490| Logic changes without effective, non-duplicated tests | §2 |
491| Public-API break without maintainer sign-off | §3 |
492| Sensitive-area change without maintainer notice | §3 |
493| Drive-by dependency bump in a feature/fix PR | §3 |
494| Guessed / hallucinated API usage | §4 |
495| Unverified or wrong external factual reference | §4 |
496| Drive-by refactors, formatting sweeps, unrelated `.gitignore` / CI edits | §4, §8.5 |
497| Placeholder work (`TODO`/`FIXME`, mocked or simplified logic presented as complete) | §5 |
498| Branch name not following `category/ticket-id-or-short-description` | §8.1 |
499| Non-standard commit message format (missing gitmoji, wrong type, non-English) | §8.2 |
500| Missing or hidden AI attribution | §8.3 |
501| Debug output or commented-out code left in the diff | §8.5 |
502| Falsely checked PR checklist items | §8.6 |
503| Force-pushing or close/reopen to reset review state | §8.7 |
504