AGENTS.md

Agent Contribution Guidelines

Language: English | 简体中文

This document defines the rules for AI agents (and the humans operating them) working on this repository — whether you are contributing a pull request or assisting a maintainer locally. It supplements, and never overrides, CONTRIBUTING.md and the Compatibility Policy.

dio is one of the most depended-on packages in the Dart/Flutter ecosystem. A single careless change can break tens of thousands of downstream projects. Contributions here are not a playground: every change must be motivated, tested, and compatible.

1. Motivation first — no speculative changes

Do not invent work. A change is only acceptable when it solves a problem that actually exists.

• Every non-trivial change must be traceable to a concrete motivation: a reproducible bug, an accepted issue/discussion, an RFC-style proposal, or an explicit maintainer request. "This seems useful" is not a motivation.
• Before implementing a feature, answer these questions in the issue or the PR description — if you cannot, do not open the PR:
  1. What cannot be done (or is done poorly) with the current dio?
  2. Who needs this, and in which real-world scenario?
  3. Why does it belong in dio itself, instead of an interceptor, an adapter, a transformer, or a separate package? dio is intentionally extensible; most needs are served by its extension points without core changes.
  4. What is the cost — API surface, maintenance burden, compatibility risk?
• One PR, one concern. Do not bundle several unrelated features or fixes into a single PR. Bundled "improvement packs" might be closed unreviewed.
• For any user-facing feature, open an issue for discussion before writing code, unless a maintainer has already asked for it. A bare Closes #NNNN is not the same as prior discussion: the referenced issue must show that maintainers have expressed interest or accepted the direction. Feature PRs without that grounding waste both your tokens and the maintainers' time, and might be closed.

2. Tests are mandatory for logic changes

Every behavioral change must be proven by tests.

• Any change to logic requires new tests or adjustments to existing tests that fail without the change and pass with it. Bug fixes must include a regression test that reproduces the original report.

• CI reports coverage diffs on every PR. The published minimum threshold is low, but that is a floor, not a target: coverage of code you changed should not regress, and new logic (including error paths) should be covered by real assertions.

• Tests must be effective and non-duplicated:

  • Assert observable behavior, not implementation details.
  • Do not add tests that merely re-execute existing covered paths to inflate coverage numbers.
  • Search the existing suites first — extend an existing test group instead of creating a near-duplicate file.

• Put tests in the right place:

  • Package-specific behavior → <package>/test/.
  • Behavior that must hold across all adapters/platforms → the shared dio_test package.

• Run the checks locally before claiming they pass:

  melos run format   # or format:fix
  melos run analyze
  melos run test     # or targeted: test:vm / test:web / test:flutter

• Never state that tests pass without having run them. Never check a PR checklist item you have not actually done. Misreporting verification status may lead to the PR being closed.

3. Compatibility is sacred — avoid breaking changes

dio's public API is a contract with an enormous downstream. Treat every public symbol as frozen unless a maintainer decides otherwise.

• Default to non-breaking. Prefer additive changes: new optional named parameters with safe defaults, new classes, new extension points.

• Do not change public method signatures, remove/rename public symbols, change default behavior, or alter thrown exception types without going through a deprecation cycle. Breaking changes belong in major releases. As dio's own CHANGELOG preamble states, unavoidable breaking changes may occasionally ship in minor releases — those still require maintainer sign-off in advance and an entry in the Migration Guide.

• If an API must go away, deprecate first and keep it working:

  @Deprecated('Use XXX instead. This will be removed in X.0.0')

  Deprecations must state their replacement and the removal version, and are only removed in the next major release, together with an entry in the Migration Guide. Target the next major, not a version beyond that.

• Do not raise the minimum Dart/Flutter SDK constraint of any package unless required by the Compatibility Policy or its listed exceptions. CI tests against the minimum supported SDK; do not use language/library features beyond a package's lower bound.

• Watch for behavioral breaking changes too: changing defaults, header normalization, redirect/error semantics, or timing/ordering of interceptors can break downstream even when signatures are untouched.

• If a breaking change is genuinely unavoidable, stop and raise it in an issue for maintainers to decide. Do not merge-request it unilaterally.

Extra scrutiny in security- and network-critical areas

Some parts of dio have oversized blast radius when broken. Changes here require extra care, and the PR description should explicitly call the change out and @-mention a maintainer:

• SSL / TLS handling and certificate pinning (badCertificateCallback, SecurityContext, adapters' HttpClient configuration).
• Redirect handling and cross-origin behavior (redirect policy, header forwarding, cookie leakage across redirects).
• Cookie management (dio_cookie_manager, domain / path matching).
• Header handling (Authorization, Content-Type, casing, duplicates).
• Timeout, cancellation, and connection pooling.
• The interceptor pipeline (ordering, error propagation, next / resolve / reject semantics).
• Request-body encoding: FormData, multipart streaming, encoding detection.

Rule of thumb: if getting this wrong could leak credentials, hang a request forever, or change data on the wire, treat it as sensitive.

Test certificates and keys

Self-signed certificates and their private keys used only for local test fixtures (TLS, ALPN, pinning, etc.) are not real secrets — but committing static .key/.crt files still has costs: secret-scanner noise, package-size bloat for published artifacts, and inconsistency with this repo's convention of generating such fixtures at test time (see scripts/prepare_pinning_certs.sh).

• Prefer generating certificates at test setup (via openssl in a setUp/helper, or a setup script) over committing static files.
• If a static fixture is unavoidable, exclude it from the published package with both:
  • false_secrets in the package's pubspec.yaml (suppresses pub's leak-detection warning), and
  • a .pubignore inside the fixture subdirectory (e.g. test/certificates/.pubignore), never at the package root — a root-level .pubignore overrides the root .gitignore for the entire directory, silently re-including build artifacts and other git-ignored files in the published package.

Dependency changes

Do not bundle drive-by dependency bumps into a feature/fix PR. When a dependency change is itself the point of the PR:

• State the reason in the description (security fix, required for a new feature, upstream deprecation, etc.). "Latest is greater" is not a reason.
• Verify the change under every supported SDK version declared in the affected pubspec.yaml. Do not raise the package's SDK lower bound just to accommodate the new dependency unless the Compatibility Policy allows it.
• Prefer the narrowest constraint that solves the problem (patch > minor > major bump).
• Call out any new transitive dependencies — downstream users care about their lockfile.
• Use ⬆️ chore (or chore(deps)) as the commit type.

4. Understand before you change

• Read the surrounding code and existing patterns before editing. Match the existing style, naming, and module boundaries.

• Fix root causes, not symptoms. When a symptom is reported, locate the actual defect before patching.

• Never guess an API — neither dio's internals nor third-party packages. Read the actual source and the package's own tests/examples when unsure. If dart analyze says a member does not exist, go back to the source instead of retrying variations. Dependency source locations:

  Platform	Default location
  macOS / Linux	~/.pub-cache/hosted/pub.dev/<package>-<version>/
  Windows	%LOCALAPPDATA%\Pub\Cache\hosted\pub.dev\<package>-<version>\

  If the PUB_CACHE environment variable is set, use that location instead of the platform default.

• Verify every external fact before writing it down. Agents routinely hallucinate numbers and attach wrong labels to them — RFC numbers, issue/PR numbers, library/API version numbers, CVE identifiers, deprecation timelines, benchmark figures, attributed quotes, platform-behavior claims ("iOS X.Y and later…"). A wrong citation in a commit message, changelog, or doc comment is worse than no citation, because it misleads downstream readers and reviewers who trust it. Before writing any external fact:

  1. Look up the source and confirm it says what you claim. For RFCs, check https://www.rfc-editor.org/rfc/rfcNNNN (or https://datatracker.ietf.org/doc/rfcNNNN/) and confirm the title matches; for issues/PRs, open the link; for library versions, read the package's own changelog/source.
  2. Confirm any section anchor, version number, or quoted text you cite actually exists at that source.
  3. If you cannot verify the fact online, drop the citation and describe the observed behavior in your own words instead. Do not guess a number to make a statement look authoritative. This applies to commit messages, CHANGELOG.md, doc comments, README, and any prose in a PR description.

5. Production quality only

• No placeholder work: no TODO/FIXME left behind, no mocked or simplified logic presented as complete, no "will optimize later" code.
• Handle edge cases and error paths explicitly; never swallow errors silently.
• If you cannot finish something completely, say so explicitly and state the boundary — do not pretend it is done.

6. When to stop and ask

Agents default to "guess and proceed". Do not. Pause and check with the operator (or open a discussion issue) when:

• The task description is ambiguous and multiple reasonable interpretations would produce materially different implementations.
• Fixing the reported problem would require design changes that go beyond what was asked for.
• The right fix touches an area not obviously in scope (e.g., renaming a public API to fix an unrelated bug, or restructuring an interceptor pipeline to enable a small feature).
• You cannot reproduce the reported issue after a reasonable attempt.
• The request itself seems wrong (e.g., the "bug" is intended behavior, or the "feature" would violate a rule in this document).

Do not stop to ask permission for routine mechanical steps: running tests / format / analyze, staging files, opening a draft PR, or choices that are already decided by this document (commit format, changelog, attribution).

7. Repository layout

This is a Melos mono-repo:

Path	Package
dio/	The core package
plugins/web_adapter/	dio_web_adapter
plugins/cookie_manager/	dio_cookie_manager
plugins/http2_adapter/	dio_http2_adapter
plugins/native_dio_adapter/	native_dio_adapter
plugins/compatibility_layer/	dio_compatibility_layer
dio_test/	Shared test suites for all adapters
example_dart/, example_flutter_app/	Examples

Setup:

dart pub global activate melos
melos bootstrap

Each package versions and releases independently. Note that packages have different SDK lower bounds (see each pubspec.yaml).

8. Commits, changelog, and PR hygiene

8.1 Branch naming

Work on a feature branch named category/ticket-id-or-short-description:

• category matches the Conventional type used in the commit: feat, fix, perf, refactor, docs, test, chore, ci, style.
• Use the tracked ticket id when one exists — the issue or PR number: fix/2201, feat/2555. Combining both is fine when it aids discoverability: fix/2201-cookie-domain-match.
• Otherwise use a short description — 2–5 kebab-case words that describe the change (docs/agents-guidelines, feat/cors-preflight-warning, chore/bump-http2-3.0.0).

Rules:

• Never work on main directly.
• One branch per PR; do not reuse a merged branch for a new change.
• Keep branch names ASCII, lowercase, and short.

8.2 Commit message format — Gitmoji or Conventional

Every commit uses gitmoji at the front or a Conventional Commits type prefix. Emojis are chosen from the gitmoji specification — do not invent new ones.

<gitmoji> <Short imperative subject>
(or)
<type>[(<scope>)]: <short imperative subject>

[optional body — wrap at ~72 chars]

[optional footer, e.g. Closes #1234]

Gitmoji commonly used in this repository (see git log for the full set). Pick one column — never both. Each row maps a gitmoji to its equivalent Conventional-type prefix; you use the emoji or the type, not the two glued together. 🔧 chore: ... is wrong.

Gitmoji	Conventional type	Use for
✨ :sparkles:	feat	New user-facing feature
🐛 :bug:	fix	Bug fix
⚡️ :zap:	perf	Performance improvement
♻️ :recycle:	refactor	Refactor with no behavior change
📝 :memo:	docs	Documentation
✅ :white_check_mark:	test	Tests only
🚨 :rotating_light:	fix / style	Fix linter or analyzer warnings
🥅 :goal_net:	fix / refactor	Catch errors / improve error handling
🔧 :wrench:	chore	Config / tooling
👷 :construction_worker:	ci	CI / workflow changes
💚 :green_heart:	ci	Fix a failing CI job
⬆️ :arrow_up:	chore	Bump a dependency
🔥 :fire:	chore / refactor	Remove code or files
🎨 :art:	style	Formatting / structure only
🔖 :bookmark:	chore(release)	Release (maintainers only)

Rules:

• Subject is an imperative English sentence. Do not append the PR number — GitHub adds (#N) automatically on squash-merge.
• Use scope when it clarifies (fix(dio_web_adapter): ...); omit when it would just repeat the file path.
• Position 0 is either the emoji or the Conventional prefix plus colon, then a space, then the subject.
• After a gitmoji the subject starts with a capital letter (🐛 Allow ..., 📝 Clarify ...); after a Conventional prefix the subject stays lowercase (docs: add ..., perf(dio): reduce ...).

Examples (adapted from actual repo history):

🐛 Allow `callFollowingErrorInterceptor` when rejecting in `ErrorInterceptorHandler`
perf(dio): reduce `FormData.readAsBytes` memory usage for large payloads
docs: add agent contribution guidelines

Do not combine the two styles:

❌ 🔧 chore: group codeql-action updates      (both gitmoji AND prefix)
✅ 🔧 Group codeql-action updates              (gitmoji only, capitalized subject)
✅ chore: group codeql-action updates          (Conventional only, lowercase subject)

8.3 AI attribution — mandatory

Transparency about AI involvement is required. Do not hide it, and do not skip it "to keep the commit clean".

• Add a Co-Authored-By: trailer for every AI agent that produced code, tests, or docs in the commit:

  Co-Authored-By: Claude <noreply@anthropic.com>
  Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
  

  Use the identity the agent itself publishes (see its own docs / recent commits from that agent on GitHub). Multiple agents → multiple trailers.

• Also disclose in the PR description which agent(s) were used and for what stage — design, implementation, tests, or review. One line is enough, e.g.:

  Implementation and tests by Devin; local review pass by GLM-5.2.

• AI attribution never shifts accountability. The human submitting the PR owns every line, must understand it, and must respond to review feedback substantively. "The AI wrote it" is not an answer to a review question.

8.4 CHANGELOG and docs

• Update the CHANGELOG.md of every package you changed, under ## Unreleased (replace *None.*).
• One concise bullet per change, written for downstream users, not for reviewers.
• Do not bump version numbers — releases are handled by maintainers.
• When public APIs change, also update README.md, README-ZH.md, API doc comments, and any affected examples.

8.5 Self-review your diff before every commit

Always inspect what you are about to commit:

git diff                          # unstaged
git diff --staged                 # staged
git diff <base-branch>...HEAD     # full branch diff before opening/updating a PR

Remove before committing:

• Debug output (print, debugPrint, console.log, temporary logs).
• Commented-out code left from earlier attempts.
• Reformatting or import re-ordering of files that are not the subject of this change.
• Unrelated bumps in pubspec.yaml / pubspec.lock.
• Whitespace-only changes in unrelated files.
• Editor/OS junk (.DS_Store, .idea/, personal scratch files).

If you cannot explain why a hunk is in the diff, it does not belong in the commit. Never use git add . or git add -A — stage files by path.

Also re-read the commit message against the staged diff. A message carried over from a previous attempt, or auto-completed from an unrelated commit, is easy to miss and lands verbatim in history. If the message and the diff describe different work, one of them is wrong.

8.6 Opening the PR

• Open as a draft PR (Create draft pull request) when the change is large, exploratory, or when you want maintainer direction before polishing. Convert to Ready for Review once local checks pass and the description is complete.

• Reference the closing issue with Closes #NNNN in the description.

• Follow the AI attribution rules in §8.3: disclose which agent(s) contributed and at which stage.

• Write PR titles and bodies in English, in the same commit style as §8.2.

• Only tick a PR checklist item that is genuinely done. For items that do not apply, keep the box unchecked and add (not applicable — reason) next to it. Do not check "done" as a shortcut.

• Describe verification honestly — no boilerplate "Test plan" checklist. In prose, state what you actually confirmed and how, in one or two sentences:

  Added 15 unit tests covering method / content-type / custom-header combinations; melos run test:vm and melos run analyze clean.

  Do not paste a generic checklist — this is the anti-pattern this section is explicitly rejecting, even if your agent tooling suggests one by default:

  ❌  ## Test plan
      - [ ] Tests pass
      - [ ] Feature works as expected
  

  Mechanical prerequisites (dart analyze, dart format) are already covered by the PR template's top-level checklist — do not re-list them as "tests". Behavioral verification means checks that would fail if this change regressed.

  If something that ought to be verified genuinely could not be — needs browser CI, a physical device, production load, and so on — list it under a short Unverified paragraph explaining why. Unverified items are known risks; this should stay rare, not become routine.

8.7 Review iteration workflow

After opening the PR:

• Address feedback with new commits appended to the branch, not by squash-and-force-push. Maintainers rely on incremental history during review; squashing happens at merge time.
• Avoid git push --force on a branch that already has review comments — it detaches those comments from their code position. If a rebase is genuinely required (e.g., conflict resolution against main), leave a comment before pushing so reviewers know.
• Do not close and reopen the PR to reset review state, retry CI, or bypass a blocking review. Push a fix instead.
• Design-level feedback is a conversation, not an instruction. If a reviewer's suggestion changes the intent of the PR (not just its implementation), reply first and reach agreement before writing new code. Blindly applying a large suggestion is worse than discussing it.
• Mark review threads resolved only after you have addressed the point in code and left a reply explaining what changed — or after the reviewer explicitly says so. Do not silently resolve.
• CI failures: read the failing job's log, find the root cause, then push a fix. Never re-run CI hoping for a green run. If a test is genuinely flaky, say so in a comment — do not paper over it by disabling the test or adding retries.

9. Patterns that may lead to closure

Quick cross-reference — each pattern is a violation of the rules above. PRs matching one or more of these may be closed without detailed review at the maintainers' discretion.

Pattern	See
No motivation or prior maintainer discussion	§1
Multiple unrelated changes bundled in one PR	§1
Logic changes without effective, non-duplicated tests	§2
Public-API break without maintainer sign-off	§3
Sensitive-area change without maintainer notice	§3
Drive-by dependency bump in a feature/fix PR	§3
Guessed / hallucinated API usage	§4
Unverified or wrong external factual reference	§4
Drive-by refactors, formatting sweeps, unrelated .gitignore / CI edits	§4, §8.5
Placeholder work (TODO/FIXME, mocked or simplified logic presented as complete)	§5
Branch name not following category/ticket-id-or-short-description	§8.1
Non-standard commit message format (missing gitmoji, wrong type, non-English)	§8.2
Missing or hidden AI attribution	§8.3
Debug output or commented-out code left in the diff	§8.5
Falsely checked PR checklist items	§8.6
Force-pushing or close/reopen to reset review state	§8.7