From: "hsbt (Hiroshi SHIBATA) via ruby-core" Date: 2023-04-24T06:36:37+00:00 Subject: [ruby-core:113325] [Ruby master Misc#19613] Add version information to all function documentation Issue #19613 has been updated by hsbt (Hiroshi SHIBATA). @fulldecent Your tone is unfriendly. Please be more respectful for all developers. ---------------------------------------- Misc #19613: Add version information to all function documentation https://bugs.ruby-lang.org/issues/19613#change-102883 * 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/