From: "fulldecent (William Entriken) via ruby-core" Date: 2023-04-23T14:41:56+00:00 Subject: [ruby-core:113315] [Ruby master Bug#19613] Add version information to all function documentation Issue #19613 has been updated by fulldecent (William Entriken). Description updated fix ---------------------------------------- Bug #19613: Add version information to all function documentation https://bugs.ruby-lang.org/issues/19613#change-102871 * Author: fulldecent (William Entriken) * Status: Open * Priority: Normal * Backport: 3.0: UNKNOWN, 3.1: UNKNOWN, 3.2: UNKNOWN ---------------------------------------- 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.) -- 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/