Skip to content

Add naming and option-unit rules to adaptor guidance - #1834

Closed
jackohilts wants to merge 1 commit into
adaptor-gen-guidancefrom
claude-adaptor-naming-guidance
Closed

jackohilts wants to merge 1 commit into
adaptor-gen-guidancefrom
claude-adaptor-naming-guidance

Conversation

@jackohilts

Copy link
Copy Markdown
Contributor

Summary

Adds two rules from mtuchi's review of the openstreetmap adaptor (#1833) to the adaptor generation and review guidance. Stacked on #1829: it targets that branch and adds to the Design Rules section #1829 introduces.

Details

The two rules:

  1. Name functions with a verb for what they do, not after the endpoint they call. runQuery, not interpreter. This applies to helpers in Utils.js too.
  2. Options with a unit say it in the name. For example timeoutMs and queryTimeoutSeconds, and never two options with the same name in different units. In Add openstreetmap adaptor (read-only, via the Overpass API) #1833, RequestOptions.timeout was in milliseconds and QueryOptions.timeout was in seconds.

Where they go:

  • claude.md: two new bullets under Design Rules, so generation applies them.
  • wiki/best-practice.md: a new "Naming" section under Common Patterns, with the reasoning.
  • wiki/code-review.md: two checklist items under API design, linking to the new section. Both are at the default severity for API design (Recommended).

The rules apply to new code. Common's request keeps its existing timeout (ms) option.

Notes:

AI Usage

Please disclose how you've used AI in this work (it's cool, we just want to
know!):

  • I have used Claude Code
  • I have used another model
  • I have not used AI

You can read more details in our
Responsible AI Policy

Review Checklist

Before merging, the reviewer should check the following items:

  • Does the PR do what it claims to do?
  • If this is a new adaptor, added the adaptor on marketing website ?
  • If this PR includes breaking changes, do we need to update any jobs in
    production? Is it safe to release?
  • Are there any unit tests?
  • Is there a changeset associated with this PR? Should there be? Note that
    dev only changes don't need a changeset.
  • If there is a changeset, was pnpm run version used to bump versions (not
    pnpm changeset version directly)? This ensures changelog dates are stamped correctly.
  • Have you ticked a box under AI Usage?

Generated by Claude Code

From review of the openstreetmap adaptor (#1833): name functions with a
verb for what they do rather than after the endpoint they call, and put
the unit in option names that have one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01De8BkeiGnA7aM4fARhetDC
@mtuchi

mtuchi commented Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Hey @jackohilts thanks for the suggestion, I have incorporated you suggestion in this pr #1829

@mtuchi mtuchi closed this Oct 30, 2026
@mtuchi
mtuchi deleted the claude-adaptor-naming-guidance branch October 30, 2026 14:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Closed

Development

Successfully merging this pull request may close these issues.

3 participants