Misc #15487

Clarify default gems maintanance policy

Added by zverok (Victor Shepelev) about 2 months ago. Updated about 2 months ago.



In addition to #15486, I'd like to raise the question of the general maintanance policy for "default" Ruby gems, in particular:

  • who is responsible for each gem and how they should be contacted?
  • what are goals and policies for gems code quality and documentation?
  • where do default gems are discussed?
  • what are some promises/guarantees default gems maintainers try to fulfill?

The most demonstrative example I'd like to point is json gem:

  • The source at ruby/json is NOT authoritative as far as I can tell, the authoritative one is flori/json
  • The gem still holds signs of the times it was independent (Pure and Ext JSON implementations, but Pure is not copied into the ruby/lib on releases, rendering standard docs pretty weird), and has NO mention it is THE json gem of Ruby
  • The gem seems unmaintained, considering the amount of PRs and issues, lot of them without any reaction for months
  • When I tried to update JSON docs, in core tracker issue I was asked to make a PR to "upstream repository", but there, the PRs (#347, #349) was simply ignored; Ruby 2.6 was released without new docs, despite the fact PRs were made at March and require almost no code review (unlike even some promising optimization PRs, that were also hanging there since Feb/Mar)

It is just one unfortunate case (TBH, my experience with contributing to other libraries, like csv and psych was much smoother), but it demonstrates some common lack of transparency in maintaining of Ruby's standard library


Updated by marcandre (Marc-Andre Lafortune) about 2 months ago

Much of this is in this list of maintainers and basic maintainers guidelines

As for the json gem, I agree it should be made clear which is the authoritative repository. I can help with maintainership too.

Updated by hsbt (Hiroshi SHIBATA) about 2 months ago

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

json is not a good example of default gems. Because I and nalsh got the only commit bit of flori/json at recently, not release a grant of

Updated by naruse (Yui NARUSE) about 2 months ago

Some of libraries has upstream and others are originated in ruby repo.
And some upstreams are not maintained but some of such libraries are transfered its privilege to hsbt.

Such historical reasons are hard to explain.
OSS project depends on volunteer and explanation itself takes much cost.
Read doc/maintainers.rdoc and logs of mailing list and related issues.

Anyway just about json.gem, you should imagine what the conclusion will be.

Updated by zverok (Victor Shepelev) about 2 months ago

naruse (Yui NARUSE) Sorry if my original request was sounding too aggressive, just stating "something is wrong" is never my intention.

Such historical reasons are hard to explain.

Yes, I understand that.

OSS project depends on volunteer and explanation itself takes much cost.

I understand that too. That's the exact reason I am asking: I'll gladly volunteer to improve the documentation and add missing one, I just want to have a deeper understanding of the matters.

My current "main" work for Ruby is The Ruby Reference, and working on it had already proven to be a source of some insights (you can look into my recent contributions to docs of core classes, which was sourced exactly from compiling The Reference).

So, going towards more practical matters, I am thinking about this:

  • contributing.rdoc: add "Contributing to default gems" section, which should explain:
    • that default gems "master" source is on GitHub, and just copied back to Ruby before release;
    • where are API changes discussed
    • what are general policies of default gem changes
  • maintainers.rdoc:
    • add missing links to GitHub repositories
    • explain what does it mean "unmaintained"
    • clearly state problematic repositories (if any), like json, where Ruby maintainers can't commit to the library, actually
  • Gem's docs: add links back to aforementioned policies, or reinclude their text.

So, my real questions are:

  1. First and most important: would it be welcomed if I'll contribute the texts as described above?
  2. The main place for discussing new features: is it this tracker or GitHub issues? (I've seen statements from different maintainers claiming one or another, for different gems). It is probably OK if it is different for different gems, but also should be documented.
  3. Are there any parts of the standard library that are "implicitly retired"? (In some discussions, date seemed so?) Meaning they are not removed for backward compatibility, but they should be considered rather "frozen" (no new features anticipated or welcomed).
  4. What does "unmaintained" in maintainers.rdoc mean? If, say, I'd like to change something about date, there wouldn't anybody to discuss/merge/review it?.. Isn't it necessary to call to community for a new maintainers?
  5. What's current status of maintenance for json gem? Would it be moved to ruby organization at some point? Are there any other default gems with similar "complicated" status?

I will be happy with short/informal/incomplete answers and ready to approach the problem in an iterative manner.

Also available in: Atom PDF