1---
2stage: none
3group: unassigned
4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
5---
6
7# Rails update guidelines
8
9We strive to run GitLab using the latest Rails releases to benefit from performance, security updates, and new features.
10
11## Rails update approach
12
131. [Prepare an MR for GitLab](#prepare-an-mr-for-gitlab).
141. [Prepare an MR for Gitaly](#prepare-an-mr-for-gitaly).
151. [Create patch releases and backports for security patches](#create-patch-releases-and-backports-for-security-patches).
16
17### Prepare an MR for GitLab
18
191. Check the [Upgrading Ruby on Rails](https://guides.rubyonrails.org/upgrading_ruby_on_rails.html) guide and prepare the application for the upcoming changes.
201. Update the `rails` gem version in `Gemfile`.
211. Run `bundle update rails`.
221. Run the update task `rake rails:update`.
231. Update the `activesupport` version in `qa/Gemfile`.
241. Run `bundle update --conservative activesupport` in the `qa` folder.
251. Resolve any Bundler conflicts.
261. Ensure that `@rails/ujs` and `@rails/actioncable` npm packages match the new rails version in [`package.json`](https://gitlab.com/gitlab-org/gitlab/blob/master/package.json).
271. Create an MR with the `pipeline:run-all-rspec` label and see if pipeline breaks.
281. To resolve and debug spec failures use `git bisect` against the rails repository. See the [debugging section](#git-bisect-against-rails) below.
291. Include links to the Gem diffs between the two versions in the merge request description. For example, this is the gem diff for [`activesupport` 6.1.3.2 to
306.1.4.1](https://my.diffend.io/gems/activerecord/6.1.3.2/6.1.4.1).
31
32### Prepare an MR for Gitaly
33
341. Update the `activesupport` gem version in [Gitaly Ruby's Gemfile](https://gitlab.com/gitlab-org/gitaly/-/blob/master/ruby/Gemfile).
351. Run `bundle update --conservative activesupport`.
361. Create an MR against the Gitaly project with these changes.
371. Make this MR dependent on the MR created in the GitLab project.
381. Merged this MR only **after** merging the GitLab project's MR.
39
40### Create patch releases and backports for security patches
41
42If the Rails update was over a patch release and it contains important security fixes,
43make sure to release it in a
44GitLab patch release to self-managed customers. Consult with our [release managers](https://about.gitlab.com/community/release-managers/)
45for how to proceed.
46
47### Deprecation Logger
48
49We also log Ruby and Rails deprecation warnings into a dedicated log file, `log/deprecation_json.log`. It provides
50clues when there is code that is not adequately covered by tests and hence would slip past `DeprecationToolkitEnv`.
51
52For GitLab SaaS, GitLab team members can inspect these log events in Kibana (`https://log.gprd.gitlab.net/goto/f7cebf1ff05038d901ba2c45925c7e01`).
53
54## Git bisect against Rails
55
56Usually, if you know which Rails change caused the spec to fail, it adds additional context and
57helps to find the fix for the failure.
58To efficiently and quickly find which Rails change caused the spec failure you can use the
59[`git bisect`](https://git-scm.com/docs/git-bisect) command against the Rails repository:
60
611. Clone the `rails` project in a folder of your choice. For example, it might be the GDK root dir:
62
63    ```shell
64    cd <GDK_FOLDER>
65    git clone https://github.com/rails/rails.git
66    ```
67
681. Replace the `gem 'rails'` line in GitLab `Gemfile` with:
69
70    ```ruby
71    gem 'rails', ENV['RAILS_VERSION'], path: ENV['RAILS_FOLDER']
72    ```
73
741. Set the `RAILS_FOLDER` environment variable with the folder you cloned Rails into:
75
76    ```shell
77    export RAILS_FOLDER="<GDK_FOLDER>/rails"
78    ```
79
801. Change the directory to `RAILS_FOLDER` and set the range for the `git bisect` command:
81
82    ```shell
83    cd $RAILS_FOLDER
84    git bisect start <NEW_VERSION_TAG> <OLD_VERSION_TAG>
85    ```
86
87    Where `<NEW_VERSION_TAG>` is the tag where the spec is red and `<OLD_VERSION_TAG>` is the one with the green spec.
88    For example, `git bisect start v6.1.4.1 v6.1.3.2` if we're upgrading from version 6.1.3.2 to 6.1.4.1.
89    Replace `<NEW_VERSION_TAG>` with the tag where the spec is red and `<OLD_VERSION_TAG>` with the one with the green spec. For example, `git bisect start v6.1.4.1 v6.1.3.2` if we're upgrading from version 6.1.3.2 to 6.1.4.1.
90    In the output, you can see how many steps approximately it takes to find the commit.
911. Start the `git bisect` process and pass spec's file name(s) to `scripts/rails-update-bisect` as an argument or arguments. It can be faster to pick only one example instead of an entire spec file.
92
93    ```shell
94    git bisect run <GDK_FOLDER>/gitlab/scripts/rails-update-bisect spec/models/ability_spec.rb
95    # OR
96    git bisect run <GDK_FOLDER>/gitlab/scripts/rails-update-bisect spec/models/ability_spec.rb:7
97    ```
98
991. When the process is completed, `git bisect` prints the commit hash, which you can use to find the corresponding MR in the [`rails/rails`](https://github.com/rails/rails) repository.
1001. Execute `git bisect reset` to exit the `bisect` mode.
1011. Revert the changes to `Gemfile`:
102
103    ```shell
104    git checkout -- Gemfile
105    ```
106
107### Follow-up reading material
108
109- [Upgrading Ruby on Rails guide](https://guides.rubyonrails.org/upgrading_ruby_on_rails.html)
110- [Rails releases page](https://github.com/rails/rails/releases)
111