Skip to content

AGENTS.md

Latest commit

 

History

History
52 lines (32 loc) · 4.32 KB

AGENTS.md

File metadata and controls

52 lines (32 loc) · 4.32 KB
Raw

AGENTS.md

Notes for anyone, human or agent, changing this repository.

The two halves deploy at different speeds

  • Frontend. Everything under web/ goes live at https://check.ipfs.network as soon as a PR merges to main. There is no build step and no approval gate.
  • Backend. https://ipfs-check-backend.ipfs.io is deployed by hand to infrastructure, from a tagged release. That can lag the frontend by days.

Self-hosted deployments widen the gap further: people run whatever backend version they installed, and may point it at the frontend served from check.ipfs.network or embedded in ipfs-webui.

So assume at all times that a new frontend is talking to an older backend, and that an older frontend is talking to a new backend. Both combinations are normal, not edge cases.

Compatibility is a hard requirement

Every change to the HTTP API or to web/ must work in both directions.

  • A new web/ must keep working against an older backend. When a response lacks a field the UI wants, disable that part of the UI and render nothing. A missing field means "this backend did not answer the question", which is never the same as a negative answer. Do not show a red cross, a warning badge, or a zero in a count for something the backend never reported on.
  • An older web/ must keep working against a new backend. New response fields are additive. Do not remove a field, rename one, or change what an existing one means, since an older frontend is still reading it.
  • Guard every new field with optional chaining (resp.NewThing?.Enabled === true) and exclude unanswered items from aggregates rather than counting them as failures.

The check for this is cheap and worth running before merging anything that touches the response shape or the renderers. Build the currently released backend, capture a real response, and render it through both versions of the frontend:

$ git worktree add /tmp/old-backend <last-release-tag>
$ (cd /tmp/old-backend && go build -o /tmp/ipfs-check-old .)
$ /tmp/ipfs-check-old &                      # then POST /check and save the JSON

Feed that JSON to formatJustCidOutput and formatMaddrOutput from both the old and the new web/script.js. Identical output means the new UI stays silent about what the old backend never answered, which is the passing condition.

Browser and Service Worker checks

BrowserCheck in the response, and the "Web Browser Compatible" and "Service Worker Compatible" lines in the UI, answer a question no other check here answers: whether a browser can retrieve from a provider at all.

These checks are extremely important. Do not remove them, and do not silence them. A provider serving Bitswap over plain /ws, raw TCP or QUIC passes every other check on this page while no web page can touch it. Without these lines the tool reports such a provider as fully working, and the person debugging goes looking for a fault in their browser client that does not exist. That failure mode is the reason the checks exist (#85, #25, ipfs/service-worker-gateway#1170).

In particular:

  • Do not weaken a verdict to make more providers look reachable. Both answers report what was actually reached, by dialing browser-usable addresses on their own and by asking HTTPS endpoints for a block with an Origin header. An address that looks right but never answers is a "no".
  • Do not drop the badge, the amber card or the summary note. Making the gap visible at a glance is the point; a verdict buried in JSON does not reach the operator who can fix it.
  • Do not label a provider unreachable when the backend simply did not report on it. Absent is not "no": see the compatibility rule above.

Release process

  • version.json drives releases. Changing it on main triggers releaser.yml, which tags and publishes.
  • CHANGELOG.md accumulates entries under ## [Unreleased]. At release time that block becomes ## [vX.Y.Z] - YYYY-MM-DD and a fresh empty Unreleased skeleton goes on top.
  • A change to user-facing behaviour ships its changelog entry in the same commit.

Frontend build

web/output.css is generated by Tailwind and committed. CI does not build it. After changing any class name in web/index.html or web/script.js, run npm ci && npm run build inside web/ and commit the result, or the new classes will have no styles in production.