Skip to content

infra: create GitHub issues when bumping submodules to track follow-up docs changes #192

@marc0olo

Description

@marc0olo

Problem

The current submodule bump checklist in CLAUDE.md is synchronous — it assumes the bumping agent addresses all downstream docs impact in the same PR. This breaks down in practice:

  • A submodule may introduce new APIs that affect many pages across the repo
  • An API may exist in one language SDK but not another yet (e.g. a JS API lands before the Rust CDK catches up)
  • The bumping agent may correctly identify gaps but have no place to record them for follow-up

Concrete example that surfaced this: bumping icp-js-sdk-docs to auth v7.0.0 in PR #189 confirmed all JS/Motoko APIs, but msg_caller_info_data/msg_caller_info_signer are not yet in any released cdk-rs version. That gap has no tracking home today.

Proposal

Add a step to the "Bumping submodules" general checklist in CLAUDE.md (and AGENTS.md if applicable):

After completing the per-submodule checks, if any docs changes are identified as potentially needed but not addressed in the bump PR, open a GitHub issue with:

  • Label: documentation
  • Title: docs: follow-up changes needed after bumping <submodule> to <version>
  • Body: a short list of what was found, what was addressed in the bump PR, and what still needs work

This turns gaps into tracked work items rather than silent omissions.

Scope

  • Update the "Bumping submodules" section in CLAUDE.md
  • Decide whether the issue should always be created (even if no gaps) or only when gaps exist (recommended: only when gaps exist, to avoid noise)
  • Consider adding a label like submodule-bump for easy filtering, or reuse documentation + enhancement

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions