From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS4713 221.184.0.0/13 X-Spam-Status: No, score=-4.1 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED, SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from neon.ruby-lang.org (neon.ruby-lang.org [221.186.184.75]) by dcvr.yhbt.net (Postfix) with ESMTP id 1E20E1F770 for ; Sun, 30 Dec 2018 10:26:56 +0000 (UTC) Received: from neon.ruby-lang.org (localhost [IPv6:::1]) by neon.ruby-lang.org (Postfix) with ESMTP id 5AD7B121D77; Sun, 30 Dec 2018 19:26:53 +0900 (JST) Received: from o1678916x28.outbound-mail.sendgrid.net (o1678916x28.outbound-mail.sendgrid.net [167.89.16.28]) by neon.ruby-lang.org (Postfix) with ESMTPS id 36169121D69 for ; Sun, 30 Dec 2018 19:26:50 +0900 (JST) Received: by filter0133p3mdw1.sendgrid.net with SMTP id filter0133p3mdw1-8105-5C289D68-24 2018-12-30 10:26:48.462351895 +0000 UTC m=+822293.987748032 Received: from herokuapp.com (ec2-54-146-201-248.compute-1.amazonaws.com [54.146.201.248]) by ismtpd0023p1iad2.sendgrid.net (SG) with ESMTP id EIVKx06NTGeyQbJJgLY5EA for ; Sun, 30 Dec 2018 10:26:48.470 +0000 (UTC) Date: Sun, 30 Dec 2018 10:26:49 +0000 (UTC) From: colby@taplaboratories.com To: ruby-core@ruby-lang.org Message-ID: References: Mime-Version: 1.0 X-Redmine-MailingListIntegration-Message-Ids: 66245 X-Redmine-Project: ruby-trunk X-Redmine-Issue-Id: 15486 X-Redmine-Issue-Author: zverok X-Redmine-Issue-Assignee: hsbt X-Redmine-Sender: colby X-Mailer: Redmine X-Redmine-Host: bugs.ruby-lang.org X-Redmine-Site: Ruby Issue Tracking System X-Auto-Response-Suppress: All Auto-Submitted: auto-generated X-SG-EID: ync6xU2WACa70kv/Ymy4QrNMhiuLXJG8OTL2vJD1yS7wbTZ+fIjz4PgSXBR8GTitxMu75HQC6tlpUj qTL8zBlbxZLZfJDEWv84RwZhKqdHKwG+ZoX3A1O6inKQz8Ab8/0iwwv10PufhHjlX2LUO6rm2oA/U9 DvgQkSspCX+T/+Ib9715sVn1eV/ty7s5lWMxhA7jyuI1dvq4u1wwA8pkMg== X-ML-Name: ruby-core X-Mail-Count: 90823 Subject: [ruby-core:90823] [Ruby trunk Misc#15486] Default gems README.md X-BeenThere: ruby-core@ruby-lang.org X-Mailman-Version: 2.1.15 Precedence: list Reply-To: Ruby developers List-Id: Ruby developers List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ruby-core-bounces@ruby-lang.org Sender: "ruby-core" Issue #15486 has been updated by colby (Colby Swandale). I just come across this issue. I wanted to point out that I've been working on the: * https://github.com/ruby/logger * https://github.com/ruby/fileutils * https://github.com/ruby/irb * https://github.com/ruby/rake 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! ---------------------------------------- Misc #15486: Default gems README.md https://bugs.ruby-lang.org/issues/15486#change-76005 * Author: zverok (Victor Shepelev) * Status: Assigned * Priority: Normal * Assignee: hsbt (Hiroshi SHIBATA) ---------------------------------------- While working on [Ruby Changelog](https://bugs.ruby-lang.org/issues/15485), 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](https://ruby-doc.org/stdlib-2.6/libdoc/ostruct/rdoc/OpenStruct.html) > > 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? -- https://bugs.ruby-lang.org/