Skip to content

docs: fix stale code comments and markdown - #1702

Open
gjermundgaraba wants to merge 3 commits into
mainfrom
chore/stale-docs-comments
Open

gjermundgaraba wants to merge 3 commits into
mainfrom
chore/stale-docs-comments

Conversation

@gjermundgaraba

Copy link
Copy Markdown
Contributor

Description

Sweep of code comments and markdown outside docs/ and spec/, correcting text that no longer matches the code and removing comments that only restated it. Every edit was checked against the code it describes (e.g. latestProvableHeight takes the threshold-th highest height, not the minimum; the default dispatch poll is 1s, not 5s; the in-memory SQLite DB is per-connection, not shared; the attestation domain-separation note was checked against the pinned ibc-contracts commit).

Two commits:

  1. Comments and markdown only (52 files): no behavioural change. No #L line citations in the reference pages moved.
  2. Proto comments and CLI help text: remove the claim that PacketAttestationRequest has no height (it has height = 3), list receipts among commitment types, say "attestor names" in --attestors, and name the JSON key file in the keys help. Regenerated attestor.pb.go (make -C cli codegen-proto) and the reference pages (refgen.py all).

Out of scope, not changed here:

  • e2e clearOnStart: false is dropped. ibccli/relayer_config.go writes a plain bool with omitempty, and the CLI defaults a missing key to true. relayer_lifecycle_test.go:143 and traffic_setup.go:399 therefore never disable startup clearing.
  • Unasserted test case. store_test.go:524-526 discards the result of the inverted-range ListPacketSequences call, so that case is never checked.
  • e2e/scripts/clean.sh sweep gap. It misses relayers started with --config ibc.yml by the deploy tests, and testprover processes.
  • No release runbook. RELEASES.md lost its "Cut a release" and "Verify a release" sections in 8dfc82d; the README and release-tracker links now no longer point at them.
  • osv-scanner.toml GO-2026-4479. The ignore blames pion/dtls/v2, which no go.sum contains.
  • Dependencies.sol:4 version. It says Solidity IBC v3.0.2, but the pin is v4.0.0-rc.1. Not edited, because a comment change alters the bytecode metadata.

Reference documentation

Derived from source: 89 regions across 3 pages. refgen.py all --check is clean.

Written by hand, not derived

  • cli/cmd/ibc/keys.go: keys new / import / show Long text (rendered into 02-cli-commands.mdx)

The hand-written CLI pages (overview, tutorial, guides) were grepped for the changed wording and need no update: the second commit changes only help text and comments, not behaviour.

Checklist

  • One logical change, diff kept as small as practical
  • Commits signed off for the DCO (git commit -s), matching your commit author identity
  • AI assistance, if any, disclosed with a Co-Authored-By or Assisted-By trailer in the commit body
  • Commit messages follow Conventional Commits
  • Tests added or updated, covering expected and error paths (n/a: comments and docs only)
  • CI is green
  • SPDX license header on new files (no new files)
  • Pull request title follows Conventional Commits (the changelog is generated from it)
  • ADR merged first if this changes architecture, a public interface, or a spec (n/a)

@gjermundgaraba
gjermundgaraba requested a review from a team as a code owner November 12, 2026 17:02
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Vulnerable dependencies

1 advisory across 1 library need attention, 2 accepted.

🚨 Needs attention

Go standard library

In use: go1.26.10 — reached from cli, e2e, gen/go/solidity-abi

Advisory CVE Fixed in Summary
GO-2026-6859 CVE-2026-97054 go1.26.11 HTTP/1 server crash due to MaxBytesReader header race in net/http

Run make vulncheck for the call paths. Either upgrade the library, or add the
advisory to cli/osv-scanner.toml with a reason if no fix exists yet.

Accepted

Listed in cli/osv-scanner.toml with a reason.

github.com/cosmos/evm

In use: v0.7.3 — reached from e2e

Advisory CVE Fixed in Summary
GO-2025-3684 — no fix yet Cosmos EVM Allows Partial Precompile State Writes in github.com/cosmos/evm

golang.org/x/crypto

In use: v0.58.0 — reached from cli, e2e

Advisory CVE Fixed in Summary
GO-2026-5932 — v0.58.1-0.20261009181718-2f1f834330b2 The golang.org/x/crypto/openpgp package is unmaintained, unsafe by design, and has known security issues

From make vulncheck-json on this run: logs.

@codecov

codecov Bot commented Nov 13, 2026

Copy link
Copy Markdown

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️

Correct code comments and markdown that no longer match the code
(renamed identifiers, changed defaults, removed features, broken
links), and drop comments that only restate the next line.

Signed-off-by: agentconnect-md[bot] <297319493+agentconnect-md[bot]@users.noreply.github.com>
Assisted-by: Claude Opus 5.5
Signed-off-by: Gjermund Garaba <gjermund@garaba.net>
Drop the PacketAttestationRequest note claiming the request has no
height (it carries height = 3), list receipts among commitment types,
say "attestor" rather than "attestation" in the --attestors usage, and
name the JSON key file in the keys help text. Regenerate the attestor
bindings and the CLI and API reference pages.

Signed-off-by: agentconnect-md[bot] <297319493+agentconnect-md[bot]@users.noreply.github.com>
Assisted-by: Claude Opus 5.5
Signed-off-by: Gjermund Garaba <gjermund@garaba.net>
Fix comments the sweep left inconsistent: the deploy_test alias note,
the otel README example (record, caller attribute), the readiness test
rationale, the Deploy step order and its IFT send-call constructor, and
the OptionsFromConfig signer-alias mapping. Report awaited rather than
succeeded in the catalyst progress log, since failures are counted too.

Assisted-by: Claude Opus 5.5
Signed-off-by: agentconnect-md[bot] <297319493+agentconnect-md[bot]@users.noreply.github.com>
Signed-off-by: Gjermund Garaba <gjermund@garaba.net>
@gjermundgaraba
gjermundgaraba force-pushed the chore/stale-docs-comments branch from 08e39ae to 82e5652 Compare November 17, 2026 13:47

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants