DEV Community: T "@tnir" N

Explain why we need .ruby-version file but no ruby DSL method in Gemfile in Rails apps

T "@tnir" N — Mon, 17 Feb 2025 06:58:00 +0000

We tend to have both .ruby-version file and a ruby directive in your Gemfile, and when you might choose one over the other, or even use both. This gets to the heart of how Ruby version management works in a Rails project, and it involves understanding the roles of different tools.

tl;dr: Between Ruby on Rails 5.2 (2017) and 7.1 (2024), we had both .ruby-version and ruby directive in Gemfile, but since 7.2 (2024) we should no more have ruby directive in Gemfile. We should manage the Ruby version only in .ruby-version for your Rails applications even if you want to add contstraints.

1. The Role of .ruby-version (and version managers)

Interpreter Selection: The primary purpose of .ruby-version is to tell Ruby version managers (like rbenv, chruby, asdf) which Ruby installation to use when you're in a project directory. It's the mechanism that activates a specific Ruby.
- When you cd into a directory containing a .ruby-version file, and you're using a version manager, the version manager reads the file.
- It then modifies your shell's PATH environment variable (and potentially other environment variables) to point to the binaries (like ruby, gem, bundle, rails) of the specified Ruby version.
- This ensures that when you run ruby -v, you see the version specified in .ruby-version, and that any commands you execute (like bundle install) will use that specific Ruby installation.
System-Wide vs. Project-Specific: Version managers are designed to allow you to have multiple Ruby versions installed on your system simultaneously. .ruby-version provides a project-specific override. You might have a system-wide default Ruby, but each project can specify its own requirement.
Outside of Bundler's Scope: Crucially, .ruby-version is primarily handled by external tools (the version managers). Bundler doesn't directly interpret or enforce .ruby-version in the same way it enforces the ruby directive in the Gemfile. Bundler sees the result (the active Ruby version), but it doesn't set it.

2. The Role of the ruby Directive in Gemfile

Dependency Constraint and Compatibility: The ruby directive in Gemfile serves a different purpose. It's a constraint that Bundler uses during dependency resolution. It tells Bundler:
- "This project requires at least this version of Ruby."
- "When resolving gem dependencies, consider only gem versions that are compatible with this specified Ruby version."
Bundler's Responsibility: Bundler enforces this constraint. If you try to bundle install with an incompatible Ruby version (one that doesn't meet the requirement in the Gemfile), Bundler will raise an error and refuse to proceed.
```
# Gemfile
ruby "3.4.2"
```
If you were to run bundle install with Ruby 3.4.1 active, Bundler would error out.
Platform-Specific Rubies (Optional): The ruby directive can also be used to specify platform-specific Ruby implementations:
```
# Gemfile
ruby "3.1.6", engine: "jruby", engine_version: "9.4.12.0"
```
This tells Bundler that the project requires JRuby 9.4.12.0, which is compatible with Ruby 3.1.6 (actually Ruby 3.1).
Doesn't Activate a Ruby: The ruby directive in Gemfile doesn't change your active Ruby version. It's a declaration of a requirement, not a command to switch interpreters. This is the key difference from .ruby-version.

3. Why Both Might Be Used (and When)

Here's a breakdown of common scenarios:

Scenario 1: .ruby-version Only (Common in older projects or simpler setups)
- How it works: You rely solely on the version manager and .ruby-version to set the correct Ruby. You don't explicitly state the Ruby version in the Gemfile.
- Pros: Simpler setup, especially if you consistently use a version manager.
- Cons: Less explicit. Someone working on the project without a version manager might accidentally use the wrong Ruby and not realize it until runtime errors occur. Bundler won't warn them. Less portable to environments without the same version manager setup.
Scenario 2: ruby in Gemfile Only (Less Common)
- How it works: You rely on the ruby directive in Gemfile to enforce the Ruby version. You don't use a .ruby-version file. You might manually switch Ruby versions (perhaps with your OS's package manager) or rely on a system-wide default Ruby that happens to match the Gemfile requirement.
- Pros: Bundler will always enforce the Ruby version.
- Cons: Very inconvenient. You have to manually ensure the correct Ruby is active before running any commands. Prone to errors if you forget. Not suitable for projects requiring different Ruby versions.
Scenario 3: Both .ruby-version and ruby in Gemfile (Best Practice, and now the Rails default)
- How it works: This was the recommended approach, and it's how Rails 5.2 through 7.1 generates new projects. You used to use both files.
- Pros:
  - Best of both worlds: .ruby-version handles the automatic switching of Ruby versions, making development convenient. The ruby directive in Gemfile acts as a safety net and ensures Bundler only resolves compatible dependencies.
  - Explicit and Enforced: The required Ruby version is clearly stated in two places, reducing ambiguity.
  - Portable: The Gemfile constraint works regardless of whether a version manager is used.
  - Consistency: This combination helps ensure consistency between development, testing, and production environments.
- Cons: Slightly more complex setup (but the complexity is justified by the benefits). You need to keep the versions in both files in sync. (Rails 7.2+'s --skip-ruby-version option for rails new can help in specific cases like using Devcontainers, where .ruby-version might be redundant).
Scenario 4: .ruby-version file is present, and the ruby directive within the Gemfile is not used. However, a .gemspec file exists, specifying the required_ruby_version.
- How it Works:
  - .ruby-version: Manages the active Ruby version as described before.
  - .gemspec: If your project is also intended to be packaged as a gem (even if it's primarily an application), the .gemspec file can include a required_ruby_version setting. This is similar to the ruby directive in the Gemfile, but it applies when your project is installed as a gem into another project.
  - Bundler respects required_ruby_version from a .gemspec: When you run bundle install, Bundler will check the required_ruby_version in your .gemspec (if it exists) and ensure the currently active Ruby version satisfies that requirement. It acts like a ruby directive in the Gemfile.
- Pros:
  - Good practice if your project could potentially be used as a gem by others. Ensures compatibility when installed as a dependency.
  - Avoids redundancy: If the version is already accurately specified in the .gemspec, there's less need to duplicate it in the Gemfile.
- Cons:
  - Slightly less explicit within the Gemfile itself. A developer looking only at the Gemfile might not immediately see the Ruby version constraint.
  - .gemspec is primarily for gem packaging; if your project is only an application and never intended to be a gem, it might feel a bit out of place to use .gemspec for this.
  - This scenario is acceptable, though generally scenario 3 is preferred.

Set Ruby version in Gemfile and .ruby-version by default rails/rails#30016

rails/rails#30016 introduced ruby "3.4.2" in Gemfile file in 2017 targeting for Ruby on Rails 5.2.0. This is applied only when new Rails applications are created through rails new command.

https://github.com/rails/rails/pull/30016

Permanently remove ruby from Gemfile rails/rails#50914

7 years after its inception in 2017, rails/rails#50914 permanently removed the ruby "3.4.2" directive from Gemfile file in 2024 targeting for Ruby on Rails 7.2.0. This change looks like a so minor problem

The original commit message was misleading but @rafaelfranca explained correctly as follows:

https://github.com/rails/rails/pull/50914#issuecomment-2529739641

It is not temporary anymore. We decided to not generate ruby version in the gemfile

Personally with this change in Feb 2024 I am so glad to get rid of ruby DSL from Gemfile, which bothers me and our developers. 🎉🎉🎉

In summary, we had to use both .ruby-version and the ruby directive in Gemfile for the best combination of convenience, explicitness, and safety according to rails new by default. This had ensured that your project uses the correct Ruby interpreter and that Bundler enforces compatibility during dependency resolution. If you are using a devcontainer, you should manage the Ruby version in .ruby-version and .devcontainer/Dockerfile files by your own self, by once removing ruby directive in Gemfile and the Dockerfile to manage the Ruby version. Since then, you are free from these constraints with the balanced configurations. Thanks Rails team for these long-term improvements ❤️❤️❤️

Update Hugo with its theme

T "@tnir" N — Wed, 17 Aug 2022 07:29:00 +0000

I used to use hugo-cactus-theme (Cactus Theme) as the Hugo theme for https://tnir.gitlab.io since its inception in 2017.
At that time I could not take time to choose the theme carefully and neither have I until this week.

I found the theme I chose was deprecated and have used Hugo 0.62.2 to build the site.

As some breaking changes happened in Hugo 0.93, I was not able to directly update it to the latest and I needed to update the system to the latest (Hugo 0.101.0) in this way 😭

Choose your theme for website very carefully and create your own if you can 🍀

GitLab diff color system

T "@tnir" N — Wed, 13 Jul 2022 22:45:56 +0000

GitLab recently allows every user to modify colors in diff.

I have used the default values with Monokai syntax highlight for 7 years at GitLab.com:

However, today I found these are not perfectly configured and so I need to change it soon.

What color have used for it for 7 years?

deletion: #c87872
addition: #678528

What color should I use for it from today?

For light theme, I can choose:

deletion: #FFEBE9
addition: #E6FFEC

Why?

As I use GitHub as well as GitLab, the colors in both should be the same if possible.

Ciao! 👋

References from GitHub (as of 2022-07-13)

--color-diff-blob-addition-num-bg: #CCFFD8;
--color-diff-blob-addition-line-bg: #E6FFEC;
--color-diff-blob-addition-word-bg: #ABF2BC;
--color-diff-blob-deletion-num-bg: #FFD7D5;
--color-diff-blob-deletion-line-bg: #FFEBE9;
--color-diff-blob-deletion-word-bg: rgba(255,129,130,0.4);

GitHub's diff color as of 2014

Resources

Image courtesy of GitHub: https://github.blog/2014-09-04-better-word-highlighting-in-diffs/

tig blame online

T "@tnir" N — Wed, 22 Jun 2022 02:38:07 +0000

tig

tig blame looks like having been loved for a while in CLI environments when looking into Git history.

But where can we find tig blame online?

Candidates I can imagine

vscode.dev extension (VSCode for Web)
- for GitLens https://gitlens.amod.io/

Resource

When I am pushing to remote Git repo, the push was rejected because...

T "@tnir" N — Fri, 15 Apr 2022 02:54:20 +0000

Git' pre-push hook can be configured in repo by repo.

gitlab-org/gitlab repo introduced it with Lefthook gem.

Due to Ruby packages (via Rubygems), I need to update all the packages corresponding Gemfile/Gemfile.lock on HEAD after:

$ git checkout master (or main) && git pull

While I just wanted to modify some Markdown, why need to update all Ruby packages?

Here is the trouble I had this morning when just docs are to be updated, which demotivate me for a while:

$ git push origin HEAD
Lefthook v0.7.5
RUNNING HOOKS GROUP: pre-push

eslint (SKIP. NO FILES FOR INSPECTION)

graphql_docs (SKIP. NO FILES FOR INSPECTION)

  EXECUTE > docs-metadata
Documentation metadata found in 1 documentation files.


docs-deprecations (SKIP. NO FILES FOR INSPECTION)

haml-lint (SKIP. NO FILES FOR INSPECTION)

docs-removals (SKIP. NO FILES FOR INSPECTION)

  EXECUTE > vale
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.


  EXECUTE > markdownlint
yarn run v1.22.17
$ markdownlint --config .markdownlint.yml doc/install/requirements.md
Done in 0.38s.


stylelint (SKIP. NO FILES FOR INSPECTION)

prettier (SKIP. NO FILES FOR INSPECTION)

rubocop (SKIP. NO FILES FOR INSPECTION)

gettext (SKIP BY SETTINGS)

  EXECUTE > danger
 Could not find omniauth-alicloud-1.0.1 in any of the sources
Run `bundle install` to install missing gems.


SUMMARY: (done in 2.59 seconds)
✔️  docs-metadata
✔️  vale
✔️  markdownlint
🥊  danger
error: failed to push some refs to 'https://gitlab.com/gitlab-org/gitlab.git'

For long time, it has been that independency from Ruby looks better to me in these cases (for Git hooks).

Life is too short for me to understand why it is.

GitLab architecture 2022

T "@tnir" N — Mon, 11 Apr 2022 08:17:26 +0000

docs: revamp simplified architecture diagram

@tnir (or @tnir on dev.to) improved GitLab simple architecture diagram in March 2022.

That has been incorrect since 2018 (for more than 4 years)

As I described in the MR, it has been incorrect since January 2018. For 50 months.

As gitlab-shell!181 (merged) removed connection between GitLab Shell and Redis since 2018, !80083 (merged) (by @sunjungp) should be updated as so.

Why is the simplified architecture important?

This is the full architecture diagram (as of April XX, 2022). This is too complicated for developers (or external contributors so-called as GitLab wider community contributors).

https://github.com/gitlabhq/gitlabhq/blob/c4e79e91d7182ced2802aacfe71f49c8e6f16d4e/doc/development/architecture.md#component-diagram

Why is the image file name important?

https://www.google.com/search?tbm=isch&q=gitlab+architecture (Image search of "gitlab architecture") will not be updated soon as updated on Git as you can see:

Thanks @sunjungp (Sunjung Park for clarifying the problem and resolving it sooner.

Conclusion

After its IPO of GitLab (company), GitLab (team) will still need more numbers of wider community contributions in code. To get code contributions from the wider community, GitLab team (and GitLab core) needs to pay attentions to make new and old developers understand its architecture, which has become heavily complicated for 10 years.

See https://contributors.gitlab.com/. That has been dead after the GitLab team killed https://gitlab.com/gitlab-com/gitlab-contributors 4 years ago (in 2018).

Refs.

@tnir @ COSS // coss.community

GitHub Actions for GitLab (OSS)

T "@tnir" N — Thu, 17 Sep 2020 06:55:11 +0000

My Workflow

I implemented GitHub Actions for GitLab Development Kit quality assurance on macOS device, which is available at https://github.com/tnir/gdk-mac-testing-kit/actions .

Submission Category:

Maintainer Must-Haves

Yaml File or Link to Code

https://github.com/tnir/gdk-mac-testing-kit/blob/brew/.github/workflows/gdk.yml

{% github tnir/gdk-mac-testing-kit %}
{% github https://github.com/tnir/gdk-mac-testing-kit/blob/brew/.github/workflows/gdk.yml %}

https://gitlab.com/gitlab-org/gitlab-development-kit
{% gitlab https://gitlab.com/gitlab-org/gitlab-development-kit %}

Additional Resources / Info

https://gitlab.com/gitlab-org/gitlab-development-kit

Why?

Since early 2018, I have suggested to use GitLab CI/CD for external Git repositories, more specifically one called as GitLab CI/CD for GitHub, simply GitLab CI for GitHub. 1, 2, 3, [unpublished source]

By the end of 2019, at GitHub Universe 2019, GitHub Actions went from Beta to General Availability, so I could use this for Linux/Windows and macOS environment.

As a community (quarterly) Hackathon organizer of GitLab, GitLab Development Kit (GDK) is crucial to make hackathons successful. Many developers use macOS on their MacBook's, but the instruction documentation has not been tested continuously.

As the latest Hackathon was scheduled on 2020-09-02/03, I started to verify the entire document of GDK on GitHub Actions on 2020-08-12. At that time it was still valid through on Actions and my local environment. But a few hours later on it, it was suddenly broken. (...snip... no time to write down everything happened during the Hackathon event)

So on the Hackathon days, we spent 30 person-hours through the 3 days. If we had fully setup it, this Action would help us save 20-30 hours in total.

Even after GitHub Actions X Dev Hackathon, I will improve this Actions for the upcoming Hackathon ♥️

Photo by Richy Great on Unsplash