Standard Library Signatures Contribution Guide

Guides

• Stdlib Signatures Guide
• Syntax
• Writing Signature Guide

Steps for Contribution

1. Pick the class/library you will work for.
2. Assign yourself on the work spreadsheet (optional but recommended to avoid duplication).
3. Sort RBS members (if there is RBS files for the classes).
   • Use bin/sort stdlib/path/to/signature.rbs command and confirm it does not break definitions.
   • Committing the sorted RBSs is recommended.
4. Add method prototypes.
   • Use rbs prototype runtime --merge CLASS_NAME command to generate the missing method definitions.
   • Committing the auto generated signatures is recommended.
5. Annotate with RDoc.
   • You'll need RDoc installed. Rvm users should use rvm docs generate first.
   • Use bin/annotate-with-rdoc stdlib/path/to/signature.rbs to annotate the RBS files.
   • Committing the generated annotations is recommended.
6. Fix method types and comments.
   • The auto generated RDoc comments include arglists section, which we don't expect to be included the RBS files.
   • Delete the arglists sections.
   • Give methods correct types.
   • Write tests, if possible. (If it is too difficult to write test, skip it.)

The Target Version

• The standard library signatures targets Ruby 3.0 for now.
• The library code targets Ruby 2.7 and 3.0.

Stdlib Worksheet

You can find the list of classes/libraries:

• https://docs.google.com/spreadsheets/d/199rRB93I16H0k4TGZS3EGojns2R0W1oCsN8UPJzOpyU/edit#gid=1383307992

Assign yourself when you start working for a class or library. After reviewing and merging your pull request, I will update the status of the library.

You may find the Good for first contributor column where you can find some classes are recommended for new contributors (👍), and some classes are not-recommended (👎).

Useful Tools

• rbs prototype runtime --merge String
  • Generate a prototype using runtime API.
  • --merge tells to use the method types in RBS if exists.
• rbs prototype runtime --merge --method-owner=Numeric Integer
  • You can use --method-owner if you want to print method of other classes too, for documentation purpose.
• bin/annotate-with-rdoc core/string.rbs
  • Write comments using RDoc.
  • It contains arglists section, but I don't think we should have it in RBS files.
• bin/query-rdoc String#initialize
  • Print RDoc documents in the format you can copy-and-paste to RBS.
• bin/sort core/string.rbs
  • Sort declarations members in RBS files.
• rbs validate -r LIB Validate the syntax and some of the semantics.
• rake generate:stdlib_test[String] Scaffold the stdlib test.
• rake test/stdlib/Array_test.rb Run specific stdlib test with the path.

Standard STDLIB Members Order

We define the standard members order so that ordering doesn't bother reading diffs or git-annotate outputs.

1. def self.new or def initialize
2. Mixins
3. Attributes
4. Singleton methods
5. public & public instance methods
6. private & private instance methods

class HelloWorld[X]
  def self.new: [A] () { (void) -> A } -> HelloWorld[A]         # new or initialize comes first
  def initialize: () -> void

  include Enumerable[X, void]                                   # Mixin comes next

  attr_reader language: (:ja | :en)                             # Attributes

  def self.all_languages: () -> Array[Symbol]                   # Singleton methods

  public                                                        # Public instance methods

  def each: () { (A) -> void } -> void                          # Members are sorted dictionary order

  def to_s: (?Locale) -> String

  private                                                       # Private instance methods

  alias validate validate_locale

  def validate_locale: () -> void
end