Specification for .ruby-version

[svoop]

The .ruby-version file emerged somewhere between different Ruby version manager ecosystems, however, it's never been formally documented to my knowledge. I'm interested in your thoughts on this.

---

UPDATE: See this README and its history for the living first draft of such a spec based on this discussion.

---

Now that the latest versions of Bundler support ruby file: ".ruby-version", maybe Rubygems (and Bundler as a part thereof) would be the right place to give this omnipresent file a home. (Btw, there's no mention of file: on https://bundler.io/guides/gemfile_ruby.html as of yet.)

The trouble I have with an undocumented .ruby-version are edge cases as the ones mentioned below. A single point of truth to clarify these cases (and maybe more) would help adopters anywhere to be compatible – Ruby version managers, hosting services like Heroku or Render, custom code and of course Bundler itself.

Relaxed Ruby Version

Say you want your project to always be on the latest PATCH version of Ruby 3.2 (at the time of writing that's Ruby 3.2.2), you could set the following in .ruby-version:

3.2

This does work with some Ruby version managers, certainly does for my homebrew solution based on direnv. However try the following in the corresponding Gemfile:

ruby file: ".ruby-version"

Installing the bundle will fail with:

Your Ruby version is 3.2.2, but your Gemfile specified 3.2

For it to work, you'd have to work around this with something along the lines of:

ruby "~> #{File.read('.ruby-version').strip}.0"

Engine or Not?

Some Ruby version managers allow the selection of the engine in .ruby-version as well. The following two are therefore equivalent and both choose CRuby:

3.2.2
ruby-3.2.2

[martinemde]

I like the idea of clearly specifying this file and bundler may be a good central place to do it.

As far as I know, this is the original specification/proposal to which modifications have been made by various ruby version managers.

Supporting asdf required a little tweaking of what is allowed, so ruby 3.2.2 is also acceptable.

I also like adding support for engines as well as relaxed version matching (something bundler is very good at, ironically).

[svoop]

@martinemde A starting point for a .ruby-version specification could be the following:

See this README and its history for the living first draft of such a spec based on this discussion.

---

After brainstorming such a minimal ruleset here, we could open a new discussion and then contact the maintainers of all common version managers to ask for feedback. If we reach a consensus, the ruleset could be published as a guide on rubygems.org (maybe with a heads-up to some very common PaaS such as Heroku, Render etc)

I guess, relaxed versions could be controversial since they depend on context and therefore might break the principle of least surprise. However, there are situations where they come in incredibly handy. And along with a word of warning in the specification, it shouldn't be a problem. After all, nobody is forced to use this notation. At least some Ruby version managers support this already.

What do you think?

So, time to wrap it and get ready for the party! Happy new year!! 🍾

[andyw8]

Suggestion: Clarify that the final newline is optional. (I remember an issue with one tool because it wasn't handling both cases).

[svoop]

Very good point, added!

[svoop]

(RESOLVED)

[jenshenny]

Thanks for starting this thread and initial ideas of what the spec can be! I think the specification can be more simple in what we want to allow for.

The separator between RUNTIME and VERSION contains dash(es) or witespace(s) only: /[-\s]+/

Can we just allow for only one dash? I guess asdf allows for whitespaces but I'm assuming they do support - in .ruby-version file?

Only the first line not starting with # is read, all other lines are ignored.

I see that comments may be helpful, I don't think it's worth the added complexity. I would want .ruby-version to be max two lines (first being the version, and the second would be the optional newline). Version managers like chruby doesn't support comments when I tried it out.

[kmcphillips]

+1 on this.

If we don't have to handle comments, and say the version is on the first line, with an optional newline, then we optimize for simplicity and remove edge cases. You can script it to something like RUBY_VERSION=$(head -n 1 .ruby-version) rather than needing a parser.

[svoop]

@jenshenny Good points as well.

In fact, asdf doesn't really parse .ruby-version and only recognizes and removes the ruby- prefix, so we can safely drop everything but a dash.

Allowing only one line with optional trailing newline feels right as well. (I've added the optionalcomments since someone mentioned they might be useful on the original proposal, but personally, I've never had any use for it and head -n 1 is a fair argument, @kmcphillips

Added both.

And I've moved the living specs draft to a small repo in order to have some history.

[kmcphillips]

My example was arbitrary, and I more mean just scripting reading the first line from a file. You linked to asdf which does ruby_version="$(cat "$current_file")" which is a real world example of doing just that, and that's great. Thanks for digging into it.

[svoop]

(RESOLVED)

[simi]

Per my understanding Ruby version specified in Gemfile must be unique, otherwise it makes no sense to lock it with. Currently Bundler locks Ruby (when present in Gemfile) using following logic to find out the version (if I remember well).

rubygems/bundler/lib/bundler/ruby_version.rb

Lines 104 to 111 in 457c3be

	def self.system
	ruby_engine = RUBY_ENGINE.dup
	ruby_version = Gem.ruby_version.to_s
	ruby_engine_version = RUBY_ENGINE == "ruby" ? ruby_version : RUBY_ENGINE_VERSION.dup
	patchlevel = RUBY_PATCHLEVEL.to_s
	@system ||= RubyVersion.new(ruby_version, patchlevel, ruby_engine, ruby_engine_version)
	end

.

🤔 If you need reusable piece of code, you're most likely looking for gemspec and required_ruby_version constraint. If you need to run project with multiple Rubies (like Rails app tested for Ruby upgrade), two Gemfiles (or composed one dynamically with 2 locks) is the way.

[svoop]

@martinemde I get your point now, thanks for being so patient with me.

After giving this some more thought, I see at least to use cases with quite different needs:

1. Ruby (often Rails) app
   This code usually runs in exactly one production environment, say a SaaS like Heroku or Render. In this setting, you're absolutely right: Using a relaxed Ruby version might cause Bundler to raise in case the specific Ruby differs from the one when the bundle was installed. Best practice appears to be nailing the Ruby to one exact MAJOR.MINOR.PATCH version.
   (My experience: As part of dev teams, I'm maintaining rather large Rails apps with relaxed Ruby version and we never ran into trouble. The trick is to wait two or three days after a new PATCH release to give the CI (e.g. GitHub) and Saas (e.g. Render) time to catch up. The advantage of this approach: PATCH updates are rolling, no need to jump between different Rubies on different feature branches. The test suite makes sure, nothing bad happens at deployment and in fact, it never did so far.)
2. Ruby gem
   This code usually runs on a whole range of different engines and Ruby versions. Dependencies are set in the gemspec rather than the Gemfile and only define the oldest Ruby supported e.g. >= 3.0. In this setting, Bundler won't ever raise because Ruby is not nailed as part of the bundle.
   (My experience: I'm maintaining quite a few Ruby gems and it's very cumbersome to set Ruby to one exact MAJOR.MINOR.PATCH version because this way, every time a new PATCH version is released, you have to visit all Ruby gems and update the version manually. I don't see any benefit in this given the test suite covers a whole matrix of Rubies anyways.)

Given my experience, I'd suggest allowing relaxed versions in .ruby-version. Whether you use it or not is up to you and depends on your project. To raise awareness for this, best practice hints in the guide might come in handy. Also, Bundler could be proactive and issue a warning in case you bundle with a relaxed Ruby version, no matter whether you do ruby file: ".ruby-version" (with a relaxed version set in .ruby-version) or something like ruby "~> 3".

What do you think, what are your experiences with this?

[peterzhu2118]

I think for Ruby gems, they should not commit the .ruby-version file and instead gitignore it just like how they should do that for the Gemfile.lock. It should be up to each person cloning the gem to set their Ruby version.

[martinemde]

I think you make a good point, and I realized that one of the annoyances I run into regularly is not having ruby auto-switched during rubygems development. I proposed a PR to ignore it so I can have the file there without hassle.

While it would make sense to have this be an open dependency, maybe "3.0", that's never going to change on my local env without me intentionally installing the next patchlevel when it comes out. If you develop gems that need to work on 3.0 and up, you can use whatever you want in your .ruby-version (idea: symlink all your gems to a .ruby-version that has whatever you want to support as your lowest compatible ruby version for your local gem dev, then this switch is easy).

However, regarding the discussion at hand:

Should .ruby-version support an fuzzy version?

I think we should divide the conversation into two pieces:

1. Should the .ruby-version format specification cover fuzzy versions?
2. Should bundler support .ruby-version with fuzzy versions?

I'm leaning towards:

1. Yes, it's already supported and it must be part of the specification for the file format.
2. No for the reasons below, but I'm not rigid and could be convinced.

Right now I'm "no" on bundler support because updating .ruby-version when you want to change your locked ruby version is the most straightforward way to lock to a new version. This case of bundler locking to a ruby version is exclusive to railsy apps and it just works: 1. the ruby is installed; 2 .ruby-version is updated; 3. the version switcher switches; 4. bundler locks to it; 5. you push and your CI/deploy fails, indicating that you're on the wrong version there so you update your deployment settings to also match the same version (docker/CI); 6. you're now sure that everything is running the same version.

With fuzzy version support the update flow is: 1. the ruby is installed; 2. .ruby-version is not changed; 3. the ruby version switch does ... something? (I'm not sure if it chooses the newest one or stays because the version is satisfied) 4. bundle install maybe supports fuzzy versions so which version are we on? 5. CI passes because it's running the old ruby and the Dockerfile isn't updated; 6. You're running multiple different versions of ruby and even though ruby is very good at upgrades, how confident are you?

The fuzzy flow is probably fine for some apps and not for others, but why I'm less inclined to support it in bundler is because it's counter to the bundler philosophy of locking to a single version so that dev/CI/prod all run the same thing.

Edit: Where I'm open to fuzzy versions is if you could arrive at functionality where the .ruby-version is fuzzy, but bundler resolves and locks to a single version. Then all bundles on CI and Prod must be frozen to ensure that the ruby version isn't accidentally updated. This fits with another future consideration: I want to remove the need to copy .ruby-version into the docker container. This is annoying and we should just trust what's in the lockfile in the case where .ruby-version is referenced but missing and the bundle is frozen.

[svoop]

@martinemde As the pieces of the puzzle start falling into place, I see where my setups might fall short, quite enlightening. 😄

I think we should divide the conversation into two pieces:

1. Should the .ruby-version format specification cover fuzzy versions?
2. Should bundler support .ruby-version with fuzzy versions?

I'm leaning towards:

1. Yes, it's already supported and it must be part of the specification for the file format.
2. No for the reasons below, but I'm not rigid and could be convinced.

Your preference happens to require little changes since at least some Ruby switchers already accept fuzzy versions and Bundler does not… but bails with something like:

Your Ruby version is 3.2.2, but your Gemfile specified 3.2

Probably good enough, however, this particular case could be handled by definition.rb with a more precise message along the lines of:

Your Gemfile specified any Ruby 3.2, but Bundler requires an exact Ruby version to lock to.

(I'm not a native English speaker, so there are most likely better ways to phrase this.)

Even if someone absolutely insists on using fuzzy versions in the Gemfile, there's always the old way:

ruby "~> #{File.read('.ruby-version').strip}.0"

However, it's beauty might gently push you towards reconsideration which – as I tend to realize now – could be a good thing after all.

I'll wait for some more feedback and other points of view for now. But I still think adding an explanation with the reasoning from this discussion might be a good addition to the guide.

[svoop]

(RESOLVED)

[nirvdrum]

What does .ruby-version represent?

While I commend the effort to standardize the .ruby-version file, I'd like to also codify what it actually is. I don't mean to derail the discussion, but I think it's important to clarify since the syntax of the file should be influenced by its use case(s). I think the various threads about fuzzy versions hits upon this.

As a loose specification, I've always understood it to mean "this is the version the devs are working with" and not "this is the only version this application works with". Indeed, if you don't have the version declared in .ruby-version installed, Ruby version managers will happily activate your default Ruby and most of the time that works fine. Moreover, Ruby goes to fairly extensive lengths to ensure backwards-compatibility. In that light, I can also see the .ruby-version file to mean "this is the minimum version we anticipate working."

I'm not a fan of making the .ruby-version file a variant of a lock. Its integration into Gemfile complicates the picture. From my perspective, that move shifted .ruby-version went from being a convenience in activating Ruby versions as you switched between projects to a declarative configuration of the project. I don't believe there's consensus on that transformation. Maybe there is, but we should be deliberate about it.

There are a few situations that come to mind that a restrictive lock complicates:

1. Upgrading CRuby. Now upgrading requires adjusting this file manually. It's a new step that we haven't needed in three decades and I think it's likely to be overlooked. Even if we automate that, you wouldn't be able to test an application with both Ruby versions without constantly flipping that file. We have a mechanism for multiple Gemfiles. There is no extension I'm aware of that allows choosing between different .ruby-version files.
2. Running with alternative Rubies. Many applications that run on JRuby or TruffleRuby also run on CRuby. A common scenario I've seen teams employ is running locally with CRuby, but deploying with JRuby. Much like the previous point, trying to work with a project in multiple Ruby engines would require constantly churning on this one file, shared globally in the repo.
3. Development on Rubies. Before any Ruby release is made, core developers run real applications on local Ruby builds. It'd be quite onerous if an application wouldn't work because the .ruby-version can't refer to a local development branch. If that problem were addressed, you're still dealing with developers churning on that file.

I'm quite in favor of making .ruby-version a convenience, not a lock. Regardless of whether we want to support fuzzy versions, I don't think Bundler's integration of .ruby-version should influence that. If Bundler wants to lock down to a specific version, then it can opt to only accept a subset of the .ruby-version syntax. Fortunately, since we're defining what that syntax is, that should make things easier for Bundler.

Depending on what we determine a .ruby-version file is, it could make sense for it allow for multiple values. If we want to say the file indicates the supported Ruby versions, then having a list would help convey that information better. For compatibility, I'd suggest the first line is the "default". I suppose at that point it might make more sense to call it .ruby-versions.

[martinemde]

You can always delete the .ruby-version and Gemfile.lock when the resolution fails. I'm not sure what's worse but both approaches have their upsides and downsides. I know this recommendation has changed over time.

It seems like I maybe came across as saying "pinning to minor is the most we need." I meant quite the opposite so I apologize for my lack of clarity.

I want .ruby-version to expand in usefulness. I'm not proposing we cut any already supported behavior. It would just be nice to have a definitive way to read the file so Bundler doesn't have to continually expand its parser, especially if it could describe everything we need for engines too.

As for locking, I'm only representing the needs of people that choose to lock to a specific Ruby in their Gemfile. If you have an open .ruby-version and a locked Ruby in your Gemfile.lock, then your open version is a source of trouble rather than a benefit. You have to use the locked version in bundler no matter what the .ruby-version says. If you maintain these separately or not at all, then you don't have to worry about Bundler's strict Ruby version locking.

[svoop]

I try to wrap this thread up, please feel free to oppose:

• .ruby-version is primarily designed to set the Ruby for development. (For deployment, Gemfile.lock or gems.locked should be used instead.)
• Fuzzy versions like ruby-3.2 are an implementation reality and should be allowed as a shortcut for ~> 3.2.0 (in the context of installed Rubies).
• The decision of Bundler to introduce the ruby file: ".ruby-version" argument is a less eyesoring recognition of the common pattern ruby "~> #{File.read('.ruby-version').strip}". It effectively promotes .ruby-version to become an additional lock file for the Ruby version which (while not recommended) may be useful in certain situations. When using ruby file: ".ruby-version", Bundler expects a full version like 3.2.2 and if it gets a (legal) fuzzy version like 3.2, should raise a corresponding error. This is not an accident, but a consequence of the unorthodox use of .ruby-version as a lock file – and merits a remark/example e.g. in an FAQ accompanying a formal specification of .ruby-version.

[svoop]

@martinemde @nirvdrum Maybe you'd like to comment on my recap in the previous comment? Otherwise, I'd consider this thread resolved for now.

[svoop]

@martinemde @nirvdrum Any more thoughts on this? Otherwise, I'd consider this thread done.

[martinemde]

I think rather than "unorthodox" it is simply a preference of how to manage ruby versions. I think that it's fine to leave the spec as is with the understanding that people can use open or strict versions and that both are valid. Bundler will aim to use the "best" version of this over time. Since the spec allows open versions, it's likely that Bundler will be expected to in the near future.

[nirvdrum]

Optional Ruby Engine

With regards to Ruby engines, I haven't seen anything other than CRuby mentioned yet. For my part, requiring the engine as part of the version simplifies things. While "3.3.0" is more convenient to type, using "ruby-3.3.0" normalizes the syntax with what we do for JRuby ("jruby-9.3.4.0"), TruffleRuby ("truffleruby-23.1.2"), mruby ("mruby-3.2.0"), and others. Beyond consistency, it would allow us to cut out some extra complexity in allowing "3.3.0" to be an alias for "ruby-3.3.0".

With that said, I think it's impractical to move away from the simplified version specifier. Grammatical normalization aside, the simplified version has been inserted into many repositories and Rubyists are conditioned to treat the .ruby-version specifier the same as whatever a Ruby version manager or installer supports. Since that coupling isn't a requirement, independently of whatever .ruby-version uses, there's plenty of code out there that drives ruby-build, rbenv, rvm, etc. with the simplified version and breaking those isn't ideal.

[svoop]

Couldn't agree more!

[svoop]

To wrap this up: It's desirable to make the engine mandatory as it unifies/simplifies the parsing. However, the current behavior of Ruby version managers differs, so the question here is whether such a breaking change stands a chance to be adopted which is why I'd like to wait and see whether the Ruby version manager maintainers have a clear opinion on this one.

[svoop]

(RESOLVED)

[nirvdrum]

Alternative Ruby Engines

With regards to alternative Ruby engines, we need to define what's permissible. With the ad hoc system we have now, new Ruby implementations largely get to choose what the engine identifier is and that gets propagated through the various Ruby version managers and installers. While it would simplify parsing, I think it would be too restrictive to hard-code the list of valid engine identifiers. But, if we leave it open-ended, then the question shifts to how consumers agree on what those identifiers should be. E.g., it wouldn't be terribly helpful if two different consumers parsed .ruby-version and one expected an "rbx-" prefix and another expected "rubinius-" when specifying the Rubinius version.

Ruby has had a rich history of alternative Ruby implementations and I think we should put up as few hurdles as possible to rapidly adopt them into standard tooling. We could maintain a list of identifiers in a community repository. It wouldn't be terribly different from what we have now with the various Ruby version managers and installers defining those engine identifiers. A central repository, however, is another thing to maintain and risks becoming bureaucratic.

[svoop]

How about adding a section to the guide which lists the predominant engines along with a link to the website of the engine which then lists how they'd like to be referred to in .ruby-version? This way, the guide would only have to be edited in case a new relevant player enters the field while established ones such as TruffleRuby could maintain their engine names (e.g. truffleruby, truffleruby+graalvm) at their own discretion?

[nirvdrum]

How about adding a section to the guide which lists the predominant engines along with a link to the website of the engine which then lists how they'd like to be referred to in .ruby-version?

What guide are you referring to?

... TruffleRuby could maintain their engine names (e.g. truffleruby, truffleruby+graalvm) at their own discretion

I used the term "engine" here because that's what the issue body uses. But, it's unclear to me whether this engine should match RUBY_ENGINE. For TruffleRuby, both "truffleruby" and "truffleruby+graalvm" release set their RUBY_ENGINE == 'truffleruby'; they're semantically the same thing.

I'm a bit worried that someone will make the assumption that version.split('-').first == RUBY_ENGINE. If needed, we could move the "+graalvm" part to another region in the version specifier in order to comply with the new syntax.

[svoop]

What guide are you referring to?

The idea behind this discussion is to add a new page to the Rubygems guide which contains the specs for .ruby-version and some additional information.

I'm a bit worried that someone will make the assumption that version.split('-').first == RUBY_ENGINE. If needed, we could move the "+graalvm" part to another region in the version specifier in order to comply with the new syntax.

Good point! What do you think: If the + is used to add one ore more further characteristics of the engine as in truffleruby+graalvm, in generic terms ENGINE+CHARACTERISTICS-VERSION, would version.split('+').first == RUBY_ENGINE hold true? Seems so for TruffleRuby but I have to admit that I haven't worked with many different engines.

[svoop]

I've added build configuration flags to the spec draft.

(RESOLVED)

[nirvdrum]

Different Build Configurations

Another piece of syntax to consider is different build configurations. I could see a case where Rubies ship with both libc and musl builds or maybe with different malloc implementations. We run into something like this already with TruffleRuby.

Each release of TruffleRuby ships as a standalone native binary or as a distribution based on the JVM. Currently, we use something like "truffleruby-23.1.2" to indicate the native build configuration and "truffleruby+graalvm-23.1.2" to indicate the JVM (GraalVM) build. Packing all of that info into one string has made it easy to integrate with the Ruby version managers and installers, but using a structured file (e.g., with engine and build keys) would the version file easier to work programmatically..

[svoop]

I don't see why truffleruby+graalvm-23.1.2 shouldn't be valid syntax. For the specs truffleruby and truffleruby+graalvm would be considered two different engines, but that's just semantics. The dash is reserved as separator between ENGINE and VERSION (and must therefore appear once max), but besides this, you're free to use any characters.

but using a structured file (e.g., with engine and build keys) would the version file easier to work programmatically

Certainly, but a valid point has already been made, that .ruby-version should remain easy to read and interpret e.g. by a Bash script.

[svoop]

I've added build configuration flags to the spec draft.

(RESOLVED)

[martinemde]

Here's a weird, probably too complicated idea for which I will start a new thread.

Rubygems and Bundler target Ruby 3.0, 3.1, 3.2, 3.3, and 3.4.

What would the various version managers do if I put each of those in .ruby-version, each one on a new line?

$ cat .ruby-version
ruby-3.0
ruby-3.1
ruby-3.2
ruby-3.3

I only have chruby installed right now and it completely ignores the additional lines.

What could you do with this?

This specifies all valid rubies for a project. Any of them are allowed but the top one is selected automatically if you're not already using another compatible version.

I think this solves an issue where a gem can't have a .ruby-version file.

This also solves for cases where something targets multiple engines and they are equally important.

Version managers could also become smarter about switching, maybe making it easier to swap between usable versions or test against multiple.

This says nothing about how Bundler will handle it. Probably Bundler locks to the top one in this crazy alternate world.

If the other version managers ignore this too it could be an interesting way to solve a few of the problems that keep coming up with this file.

[svoop]

Given the discussions above which underline the origin and main purpose of .ruby-version as "the version development is currently done with", I'd rather not go down this road. The main problem: The additional entries might be ignored by (some) Ruby version managers, but it's unclear what they actually stand for and to clarify this, some sort of comments appear necessary which further bloats the spec. Also, the name .ruby-version would no longer reflect the content, it should be .ruby-versions which is a big breaking change.

I'd rather expect this information to be part of the README than literally hidden inside a dotfile.

[svoop]

@martinemde A soft version of this which wouldn't imply more additions (see me previous comment) could be as follows: Only the first line of the .ruby-version file is relevant, everything else is ignored (and therefore can be used or not ad lib). I'm not sure whether this is a good idea though, any thoughts?

[svoop]

@martinemde Any more thoughts on this? Otherwise, I'd consider this thread done.

[martinemde]

@svoop I think building in a way to make it possible to extend it in the future without breaking existing implementations makes sense. Whether that's "only first line" or allowing comments, it enables there to be a future extension that takes advantage of a part of the file that is purposely ignored.

For .ruby-version, I think it's fine to say "only the first line should be read". I don't think there's any existing implementation out there that would break from this.

[svoop]

@martinemde Thanks for the input. Given that even for a shell script, it's ridiculously easy to read just the first line, allowing for any number of lines while (for now) only honoring the first seems like a very reasonable compromise to me.

[svoop]

In case this discussion and the feedback from the Ruby version manager maintainers reaches some consensus, where would you like to see the .ruby-version spec published?

There are not too many places which come to mind, at least not to mine:

• Install Ruby guide on ruby-lang.org
• Rubygem guides
• Bundler guides

What do you think, are there any other, better places maybe?

[martinemde]

I don't know where is "right", but I could see this living in a repository, published as a single github pages website, or hosted on any of the places you suggested.

1. Hosting it in ruby-lang makes a lot of sense but I have no control over that site.
2. Bundler will eventually read the file correctly, so hosting it in the rubygems github org as a repository or in bundler docs is reasonable.
3. Rubygems.org would be happy to host, but I think it's the least good option here. Gems can't really use .ruby-version as spec'd. The bundler docs would be better than rubygems.org guides.

I vote for a repository myself.