Skip to content

docs: document typing policies and test conventions in CONTRIBUTING.md and stdlib.md - #3179

Open
zonuexe wants to merge 1 commit into
ruby:masterfrom
zonuexe:docs/guidelines-feedback
Open

zonuexe wants to merge 1 commit into
ruby:masterfrom
zonuexe:docs/guidelines-feedback

Conversation

@zonuexe

@zonuexe zonuexe commented Sep 28, 2026

Copy link
Copy Markdown
Contributor

Document typing policies and standard library test conventions based on maintainer feedback from @ksss in recent stdlib PRs (#3170, #3171, #3172, #3173).

Changes

  • docs/CONTRIBUTING.md:
    • Add upstream repository submission guidance for bundled gems per ALUMNI_STDLIBS.
    • Clarify policy against union types for bridging Ruby versions.
    • Add Q&A on void versus untyped for method return values, linking to syntax.md.
    • Add guidance on %a{annotate:rdoc:skip} for preventing duplicate RDoc imports on core class extensions.
  • docs/stdlib.md:
    • Require assert_const_type "Class" for class and exception constants, with Good and Bad examples.
    • Separate type tests from behavior tests. Skip superclass checks and constant value checks.
    • Document rules for extending existing test files and preserving existing test classes.

Verification with Coding Agents

We verified the updated documentation by testing multiple coding agents (Gemini 3.1 Pro, Gemini 3.8 Flash, and DeepSeek-v4.1-flash) on the task from #3172:

  • Without updated docs: Models generated behavior assertions (assert_equal StandardError, Error.superclass) and invalid singleton assertions (assert_const_type "singleton(::StringScanner::Error)").
  • With updated docs: All three models produced valid type tests on the first attempt, using assert_const_type "Class" and adding tests to existing test classes.

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