[ruby-core:113333] [Ruby master Misc#19613] Add version information to all function documentation
From:
"nobu (Nobuyoshi Nakada) via ruby-core" <ruby-core@...>
Date:
2023-04-25 09:05:27 UTC
List:
ruby-core #113333
Issue #19613 has been updated by nobu (Nobuyoshi Nakada). FYI, `File.exist?` has been documented before 2.0. https://docs.ruby-lang.org/en/2.0.0/File.html#method-c-exist-3F ---------------------------------------- Misc #19613: Add version information to all function documentation https://bugs.ruby-lang.org/issues/19613#change-102892 * Author: fulldecent (William Entriken) * Status: Closed * Priority: Normal ---------------------------------------- Ruby does not properly support semantic versioning. [1] Therefore, for example, the function File#exist? should specify if this function existed since Ruby 2.0.0, Ruby 3.0.0, Ruby 3.2.0 and if, maybe, Ruby 2.9.4.3.az doesn't support it. In this example, if somebody was using File#exists? and were violated to find their code stopped working with Ruby 3.2.0 they might switch to File#exist?. However by reading the documentation we don't know if File#exist? was just created in 3.2.0 to replace File#exists? or if it was created in 2.0 or 2.4 or whatever. Maybe there is some version like 2.9.8 where File#exist? didn't exist. Maybe everybody else reading this (population bias: people that use Redmine) knows this. But if you are just reading the documentation then you won't know this and you will have a painful experience. Possible solutions: 1. Update https://www.ruby-lang.org/en/news/2013/12/21/ruby-version-policy-changes-with-2-1-0/ and add a red warning at the top: RUBY HAS MADE VIOLATIONS OF SEMANTIC VERSIONING UP TO VERSION 3.2.0 THAT WE WILL NOT CORRECT. BUT STARTING IN 3.2.0 WE HAVE/WILL USE SEMANTIC VERSIONING GOING FORWARD. 2. Update https://www.ruby-lang.org/en/news/2013/12/21/ruby-version-policy-changes-with-2-1-0/ and add a red warning at the top: WE HAVE CHANGED OUR POSITION, AND WE WILL BE "INSPIRED" BY SEMVER BUT MAKE NO COMMITMENT TO USE IT COMPLETELY, WE WILL ABANDON THE WORD "SEMVER" TO AVOID CONFUSION. 3. If #1 is not done: update every function documentation to explain all versions and history notes about what applies to that function (this is what PHP does in their official documetation.) --- [1] https://stackoverflow.com/questions/14351272/undefined-method-exists-for-fileclass-nomethoderror -- https://bugs.ruby-lang.org/ ______________________________________________ ruby-core mailing list -- ruby-core@ml.ruby-lang.org To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org ruby-core info -- https://ml.ruby-lang.org/mailman3/postorius/lists/ruby-core.ml.ruby-lang.org/