Project

General

Profile

Misc #15486

Default gems README.md

Added by zverok (Victor Shepelev) 11 months ago. Updated 9 months 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?ClosedActions
Related to Ruby master - Bug #15500: Behavior of require method in 2.5 is different from 2.4 and 2.6ClosedActions

History

Updated by marcandre (Marc-Andre Lafortune) 11 months ago

I've stared improving the README for the matrix gem.

Feel free to provide PRs for it, and it could serve as a model for the others.

#2

Updated by marcandre (Marc-Andre Lafortune) 11 months ago

  • Related to Bug #15376: Default gems: how will it work exactly? added

Updated by hsbt (Hiroshi SHIBATA) 11 months ago

  • Assignee set to hsbt (Hiroshi SHIBATA)
  • Status changed from Open to Assigned

Updated by colby (Colby Swandale) 11 months ago

I just come across this issue. I wanted to point out that I've been working on the:

Repositories for the past few weeks and improving whatever i can. I find that the READMEs on the logger, fileutils, and irb projects can defiantly be improved. I've made PRs and raised issues in Github in each project.

Some ideas i have are having generated documentation be published in each project on Github. Have more comprehensive examples in the README.

I could defiantly use some help to get some ideas on how to best do this and also help to improve the rest of the gems.

Thanks!

Updated by rbjl (Jan Lelis) 11 months ago

I'd like to help out, too.

Maybe we can have a second file README-DEFAULT-GEM.md which is linked to by the README.md. The README-DEFAULT-GEM would explain how default gems work etc. and would be same for all default gems and would be updated in an automated way (i.e. one script that updates all). The README would then only contain gem specific examples, explanations, etc.

Updated by rbjl (Jan Lelis) 11 months ago

As an example, I've created such a "default gem explanation" file as PR to the matrix library, see here: https://github.com/ruby/matrix/pull/7/files

What do you all think about this approach?

#7

Updated by marcandre (Marc-Andre Lafortune) 11 months ago

  • Related to Bug #15500: Behavior of require method in 2.5 is different from 2.4 and 2.6 added

Updated by duerst (Martin Dürst) 11 months ago

rbjl (Jan Lelis) wrote:

As an example, I've created such a "default gem explanation" file as PR to the matrix library, see here: https://github.com/ruby/matrix/pull/7/files

What do you all think about this approach?

I think in general, it is a good idea to add such information.

But we have to be careful. The main issues I'm seeing with the actual PR are:

1) Where and how to submit bug reports, patches, feature requests,... may be different from gem to gem.

2) You mention https://stdgems.org/. This looks good, and seems to be up to date (I didn't do any actual checks, though). But what guarantee, if any, do we have that it will still be up to date in some years? It says "You can find out which version of matrix is included in your version of Ruby on stdgems.org/matrix.". Don't we have a way to check a gem version directly? If we don't, we should create one. I think it's okay to write something like "https://stdgems.org/ may provide additional information about gem versions", but adding yet another Web site that we depend on may be suboptimal.

Updated by rbjl (Jan Lelis) 11 months ago

Thank you for the feedback. In the GH issue the general opinion is to have a single README file with all the info.

duerst (Martin Dürst) wrote:

But we have to be careful. The main issues I'm seeing with the actual PR are:

1) Where and how to submit bug reports, patches, feature requests,... may be different from gem to gem.

This is correct, although it might not be overly complex. If I understood hsbt correctly, the goal is that all future bug reports go to gem repository directly (i.e. a repo on GitHub). Until we get there we could add another sentence with a pointer to ruby-lang ala "You can also submit your bug reports and feature requests to bugs.ruby-lang.org"

Also, if we'd choose to generate README(part)s via templates, the correct point of maintenance could be integrated easily.

2) You mention https://stdgems.org/. This looks good, and seems to be up to date (I didn't do any actual checks, though). But what guarantee, if any, do we have that it will still be up to date in some years? It says "You can find out which version of matrix is included in your version of Ruby on stdgems.org/matrix.". Don't we have a way to check a gem version directly? If we don't, we should create one. I think it's okay to write something like "https://stdgems.org/ may provide additional information about gem versions", but adding yet another Web site that we depend on may be suboptimal.

You are right, there is no guarantee and I agree with your thoughts. Nevertheless, I've also put the raw data on GitHub, so it does not depend on me solely: https://github.com/janlelis/stdgems. If there is an interest in having one I would be open to build an API around this data, so it can be requested from inside Ruby.

Updated by duerst (Martin Dürst) 11 months ago

Hello Jan,

You are right, there is no guarantee and I agree with your thoughts. Nevertheless, I've also put the raw data on GitHub, so it does not depend on me solely: https://github.com/janlelis/stdgems. If there is an interest in having one I would be open to build an API around this data, so it can be requested from inside Ruby.

Thanks for contributing to this issue. I think it's good to have this data on GitHub. It may also be a good idea to have this data accessible by a Web API.

But I still have a very fundamental question: Why isn't this information available by introspection, without having to go over the net to a Web API? Ruby itself should not have any problem providing this information, I'd guess. If I'm wrong, what's the problem?

Updated by duerst (Martin Dürst) 11 months ago

duerst (Martin Dürst) wrote:

But I still have a very fundamental question: Why isn't this information available by introspection, without having to go over the net to a Web API? Ruby itself should not have any problem providing this information, I'd guess. If I'm wrong, what's the problem?

I found $LOADED_FEATURES, but it doesn't contain the necessary information::

require 'bigdecimal'
 p $LOADED_FEATURES.grep(/bigdecimal/)

=> ["/usr/local/lib/ruby/2.6.0/x86_64-cygwin/bigdecimal.so"]

Updated by hsbt (Hiroshi SHIBATA) 9 months ago

  • Status changed from Assigned to Feedback

We welcome a patch for README.md of default gems on GitHub directly like https://bugs.ruby-lang.org/issues/15486#note-4.

Also available in: Atom PDF