Undocumented changes: uuid_v4 alias

I was using Random.uuid_v4 in Ruby 3.3. Then executed the same code on Ruby 3.2 as my code is supposed to support 3.0-3.3 and got that error:

Quite obviously there was a change between 3.2 and 3.3 and uuid_v4 was not implemented.

I searched a lot about this change, I read Ruby official release notes, third party changelogs, github release notes, etc. … and nothing.

So I looked were uuid_v4 was in the code to discover it's an alias for uuid that was there long before.

https://github.com/ruby/securerandom/blob/34ed1a2ec35dc8f00ff69665b373cef7484c937f/lib/random/formatter.rb#L177

uuid_v4 alias for uuid was introduced when uuid_v7 was introduced. It makes sense.

In securerandom: https://github.com/ruby/securerandom/commit/34ed1a2ec35dc8f00ff69665b373cef7484c937f
In stdlib: https://github.com/ruby/ruby/commit/dfb2b4cbc9aa5edc315e210bf6bfd92fcf6e45de

The introduction of uuidv7 in securerandom v0.3.0 is documented here: https://github.com/ruby/securerandom/releases/tag/v0.3.0.

The issue is uuid_v4 addition is not documented anywhere.

More generally, in Ruby, when you use a method, you have no clue when (in which version of ruby) this method was introduced. So it's quite inconvenient if you try to keep support for several versions of Ruby.

Unfortunately Ruby official documentation use plain old RDoc. While in Yard, there is a @since tag to document when a method or class was introduced. This helps a lot in that sens.

Also in the past, APIdock had a bar graph tracking Ruby changes so when browsing Ruby API via APIdock you knew in which version a change was introduced. Unfortunately, APIdock 1) is third party 2) is unmaintained since Ruby 2.6.3.

Has this topic already been discussed? Should I open an issue on Ruby issue tracker and ask the question on the mailing list?

In the meantime as far as securerandom is concerned:

1. It seems there is no release note / change log tracked in git (the only release note is the one on github release: https://github.com/ruby/securerandom/releases)
2. Could we edit v0.3.0 release (https://github.com/ruby/securerandom/releases/tag/v0.3.0) to document the fact that uuid_v4 alias was introduced?
3. I don't know how to document that change in Random::Formatter in stdlib

Start with lib/random/formatter.rb and the linked commits, then compare the securerandom v0.3.0 release page with the corresponding stdlib documentation. The issue proposes documenting the uuid_v4 alias and more generally recording when Ruby methods were introduced, but it does not settle the scope or documentation location. Done should include an agreed, published record of the alias change.