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