ruby/docs.ruby-lang.org

Documentation needs backporting

Closed this issue · 6 comments

zverok commented

docs.ruby-lang.org renders docs only for major versions: there is docs for 2.7.0, but not for 2.7.1 -- which implies that https://docs.ruby-lang.org/en/2.7.0/ actually contains "Generic 2.7 docs". At the same time, documentation is frequently fixed after the release. This way, documentation that is relevant for version x.y.*, but was NOT there at x.y.0 will NEVER be rendered. Some examples:

  1. What's the pattern matching syntax for 2.7? The PM docs were written after the release, so they are accessible by https://docs.ruby-lang.org/en/3.0.0/doc/syntax/pattern_matching_rdoc.html (it is 3.0's PM!), or https://docs.ruby-lang.org/en/master/doc/syntax/pattern_matching_rdoc.html (was 2.7's before 3.0's release, now it is 3.0's too).
  2. My method definition docs update was merged AFTER the 3.0 release. So endless methods and ... argument forwarding are documented here: https://docs.ruby-lang.org/en/master/doc/syntax/methods_rdoc.html, but not here: https://docs.ruby-lang.org/en/3.0.0/doc/syntax/methods_rdoc.html (implying they aren't in 3.0 at all)

I believe that something should be done about it, probably at least on releasing 3.0.1 its docs should be merged into 3.0.0 URL, or maybe rendered separately at https://docs.ruby-lang.org/en/3.0.1. Or, maybe, the docs should actually be backported into 3.0.0? Because if the Ruby installed with the local docs, 3.0.0 would forever lack them.

hsbt commented

We generate them from ruby_3_0 branch, not 3.0.0 or 3.0.1. So, It includes 3.0.1 fixes automatically. see https://github.com/ruby/docs.ruby-lang.org/blob/master/Rakefile#L5

What's the problem? Should we rename 3.0.0 to 3.0?

zverok commented

What's the problem?

The problem(s) are -- this is just a small subset of examples, there are more:

hsbt commented
  • here are no docs for one-line methods and args forwarding

It still working now. The root cause is our rdoc on documentation system is bundled by Ruby 2.7. We need to upgrade it.

Again, we use the HEAD commit of ruby_x_y branch. So, it's NOT backporting issue.

zverok commented

@hsbt Interesting. Am I understanding correctly that it is Ruby repo/tracker where I should ask to "backport" docs? As far as I can see, https://github.com/ruby/ruby/tree/ruby_2_7/doc/syntax doesn't have pattern_matching.rdoc either...

hsbt commented

You should file it to bugs.ruby-lang.org as backport request. It's same as feature requet/bug fix.