Skip to content

docs: add command prefix conventions contributor guide#1035

Open
BioCam wants to merge 1 commit into
PyLabRobot:mainfrom
BioCam:docs-command-prefix-conventions
Open

docs: add command prefix conventions contributor guide#1035
BioCam wants to merge 1 commit into
PyLabRobot:mainfrom
BioCam:docs-command-prefix-conventions

Conversation

@BioCam
Copy link
Copy Markdown
Collaborator

@BioCam BioCam commented May 13, 2026

Summary

Adds a contributor guide documenting standardized verb-prefix conventions for PyLabRobot method names. A method's prefix now signals both its domain (physical machine vs in-memory resource model) and its effect (action / measurement / state-read / state-write), so callers can tell from a name whether a call will round-trip over serial or stay in process.

The guide:

  • defines the prefix vocabulary (move_, aspirate_, measure_, read_, request_, set_, get_, update_, assign_, unassign_, ...) and the two tables that pin each prefix to a category,
  • lists forbidden synonyms (fetch_, retrieve_, query_, write_, ...) to keep the vocabulary tight,
  • gives a decision flow for picking a prefix when writing a new method,
  • documents edge cases (cached-vs-fresh reads, methods that act and return, model+machine writes, properties vs methods),
  • includes verified real-codebase examples and flags known non-compliant patterns as future harmonization targets.

The guide explicitly tells contributors (and AI assistants) not to silently rename existing methods as part of unrelated work — harmonization is a separate, scoped effort.

Forum discussion that led to this convention: https://discuss.pylabrobot.org/t/standardised-plr-command-prefix-proposal/403

Test plan

  • make docs builds without warnings
  • New page renders in the contributor guide General section
  • All collapsible <details> blocks open/close in the rendered HTML
  • Internal links (forum, GitHub trackers) resolve

🤖 Generated with Claude Code

Documents a standardized verb-prefix vocabulary for PLR methods so a
method's name reveals both its domain (physical machine vs in-memory
resource model) and its effect (action / measurement / state read /
state write). Adds the guide to the General section of the contributor
toctree.

Convention discussion: https://discuss.pylabrobot.org/t/standardised-plr-command-prefix-proposal/403

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@BioCam BioCam requested a review from rickwierenga May 13, 2026 05:28
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.

1 participant