Misc #8835

Updated by knu (Akinori MUSHA) about 10 years ago

 [This is a presentation for [[ruby:DevelopersMeeting20130831Japan]].] ((<DevelopersMeeting20130831Japan|URL:>)).] 

 Ruby's versioning scheme is currently not well defined or well 

 First, RUBY_API_VERSION was introduced in 1.9.1, but has not been 
 properly maintained since then.    There must have been at least a few 
 ABI incompatible changes (although we tried hard to keep source level 
 compatibility) and many API additions between 1.9.1 and 1.9.3, but 
 RUBY_API_VERSION was never bumped. 

 Secondly, it looks like TEENY version is fixed to zero in the 2.x 
 series without being used effectively.    We often find overlooked 
 incompatibility or feature bugs after an official release x.y.0, and 
 would like to fix them in a backward compatible way.    I'd suggest we 
 accept such a situation will happen, and bump TEENY when such a fix 
 that affects forward compatibility is made.    We have up to nine times 
 of chance for fixing such a situation, and shouldn't be too worried 
 about running out of digits. 

 So, here I propose introducing a new versioning scheme as follows, 
 much with Semantic Versioning ( in mind: 

 (1) From 2.1.0 and on, RUBY_API_VERSION shall match RUBY_VERSION. 

     Giving them different numbers has been a source of confusion, and 
     introducing this scheme is a way to provide RUBY_VERSION with how to 
     read API compatibility from the numbers. 

 (2) MINOR version is incremented when an incompatible API change is 

     In practice, it is incremented before a change to break 
     compatibility is actually made.    It is when When a relatively significant 
     amount of change is going to be made, which would break 
     compatibility, or hurts stability for a certain period of time. 

     Before making such a change, a new stable branch 
     ruby_{MAJOR}_{MINOR} is cut off from trunk, and MINOR version is 
     bumped on trunk.    MAJOR version may be incremented instead, 
     resetting MINOR to zero. 

     On the ruby_{MAJOR}_{MINOR} branch, when the time comes for 
     prereleasing {MAJOR}.{MINOR}.0, a new branch 
     ruby_{MAJOR}_{MINOR}_0 is cut off from the ruby_{MAJOR}_{MINOR} 

 (3) TEENY version is incremented when functionality is added in a 
     backward-compatible manner. 

     It happens on ruby_{MAJOR}_{MINOR} branches, where a new branch 
     ruby_{MAJOR}_{MINOR}_{TEENY} is cut off when it is released, 
     resetting PATCHLEVEL to zero. 
 (4) PATCHLEVEL is initialized to zero on each 
     ruby_{MAJOR}_{MINOR}_{TEENY} branch where TEENY > 0 on creation, 
     and incremented every time a change is made on the branch. 

     On a ruby_{MAJOR}_{MINOR}_0 branch, PATCHLEVEL is kept at -1 
     during the prerelease period.    It is set to zero when 
     {MAJOR}.{MINOR}.0 is officially released. 

     On other branches, it is fixed to -1. 

 Note that MINOR and TEENY need not be bumped every time an applicable 
 change is made, but once before a new official release is rolled out 
 from the branch. 

 With this scheme introduced, version specific library subdirectory 
 names only need to have {MAJOR}.{MINOR} in it, and user can safely 
 upgrade ruby to a new teeny version without having to rebuild and 
 reinstall already installed libraries. 

 [Figure: Branch Tree] 

        \                         \ 
         o--o--o--o--(ruby_2_1)    o--o--...--(ruby_2_2) 
             \    \    \                   \ 
              \    \    \                   o--[v2_2_0_0]--...--(ruby_2_2_0) 
               \    \    \ 
                \    \    o--[v2_1_2_0]--[v2_1_2_ppp]--...--(ruby_2_1_2) 
                 \    \ 
                  \    o--[v2_1_1_0]--[v2_1_1_ppp]--...--(ruby_2_1_1)