Undocumented changes: uuid_v4 alias

[noraj]

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.

securerandom/lib/random/formatter.rb

Line 177 in 34ed1a2

alias uuid_v4 uuid

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

In securerandom: 34ed1a2
In stdlib: ruby/ruby@dfb2b4c

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

[noraj]

Other languages tries to do this

E.g. Python:

E.g. nodejs