Skip to content

Latest commit

 

History

History
98 lines (72 loc) · 3.87 KB

CONTRIBUTING.md

File metadata and controls

98 lines (72 loc) · 3.87 KB

Standard Library Signatures Contribution Guide

Guides

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 2.7 for now.
  • The library code targets Ruby 2.6, 2.7, and 3.0.

Stdlib Worksheet

You can find the list of classes/libraries:

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 stdlib/builtin/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 stdlib/builtin/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.

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 dicionary order

  def to_s: (?Locale) -> String

  private                                                       # Private instance methods

  alias validate validate_locale

  def validate_locale: () -> void
end