Project

General

Profile

Actions

Misc #15486

open

Default gems README.md

Added by zverok (Victor Shepelev) almost 3 years ago. Updated over 2 years ago.

Status:
Feedback
Priority:
Normal
[ruby-core:90803]

Description

While working on Ruby Changelog, I noticed the following.

A lot of parts of stdlib is extracted currently into "default gems". This, in my understanding, means (amongst other things) their development is now in separate repositories on GitHub, and their development is semi-independent.

The problem I'd like to emphasize is their README is unclear about "what is it". Let's look at ostruct for example: https://github.com/ruby/ostruct. There are two huge problems:

  • Stumbling upon this repo, how should one know it is a) a part of Ruby stdlib? and b) the authoritative source of this part (and not a mirror of the code in ruby/ruby repo)?
  • There is some basic documentation explaining the usage of the library, but it would NOT be rendered anywhere in the standard library docs, so it is basically useless (which is not obvious for repo contributors).

I believe that for standard library gems the README should look somehow as following:

This is the development repository of Ruby ostruct (OpenStruct) standard library.

The library provides an OpenStruct data structure, similar to a Hash, that allows the definition of arbitrary attributes with their accompanying values.

Canonical library docs: OpenStruct

Before participating in the development of ostruct, you should know the following:

  • The development process is standard "fork => commit => pull request"
  • New versions of the standard library are released with new versions of Ruby
  • Versioning policy: ...
  • Code quality policy: ...

The last two points should probably link to the common documentation for all "default gems"... Well, as well as the whole text. So, all in all, there should be README template, where only gem names, short descriptions, and links to "canonical docs" are different (and maybe some code structure/contribution details for bigger libraries).

WDYT?


Related issues

Related to Ruby master - Bug #15376: Default gems: how will it work exactly?Closedhsbt (Hiroshi SHIBATA)Actions
Related to Ruby master - Bug #15500: Behavior of require method in 2.5 is different from 2.4 and 2.6Closedhsbt (Hiroshi SHIBATA)Actions
Actions

Also available in: Atom PDF