debian-mirror-gitlab/doc/development/gemfile.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

146 lines
6.7 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
stage: none
group: unassigned
2021-02-22 17:27:13 +05:30
info: 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
2021-01-29 00:20:46 +05:30
---
2017-08-17 22:00:37 +05:30
# `Gemfile` guidelines
When adding a new entry to `Gemfile` or upgrading an existing dependency pay
attention to the following rules.
2019-12-04 20:38:33 +05:30
## No gems fetched from Git repositories
2017-08-17 22:00:37 +05:30
2019-12-04 20:38:33 +05:30
We do not allow gems that are fetched from Git repositories. All gems have
2017-08-17 22:00:37 +05:30
to be available in the RubyGems index. We want to minimize external build
dependencies and build times.
## License compliance
Refer to [licensing guidelines](licensing.md) for ensuring license compliance.
2021-03-11 19:13:27 +05:30
2021-06-08 01:23:25 +05:30
## GitLab-created gems
Sometimes we create libraries within our codebase that we want to
extract, either because we want to use them in other applications
ourselves, or because we think it would benefit the wider community.
Extracting code to a gem also means that we can be sure that the gem
does not contain any hidden dependencies on our application code.
In general, we want to think carefully before doing this as there are
also disadvantages:
1. Gems - even those maintained by GitLab - do not necessarily go
through the same [code review process](code_review.md) as the main
Rails application.
1. Extracting the code into a separate project means that we need a
minimum of two merge requests to change functionality: one in the gem
to make the functional change, and one in the Rails app to bump the
version.
1. Our needs for our own usage of the gem may not align with the wider
community's needs. In general, if we are not using the latest version
of our own gem, that might be a warning sign.
In the case where we do want to extract some library code we've written
to a gem, go through these steps:
1. Start with the code in the Rails application. Here it's fine to have
the code in `lib/` and loaded automatically. We can skip this step if
the step below makes more sense initially.
1. Before extracting to its own project, move the gem to `vendor/gems` and
load it in the `Gemfile` using the `path` option. This gives us a gem
that can be published to RubyGems.org, with its own test suite and
isolated set of dependencies, that is still in our main code tree and
goes through the standard code review process.
- For an example, see the [merge request !57805](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57805).
1. Once the gem is stable - we have been using it in production for a
while with few, if any, changes - extract to its own project under
2021-12-11 22:18:48 +05:30
the [`gitlab-org/ruby/gems` namespace](https://gitlab.com/gitlab-org/ruby/gems/).
- To create this project:
2022-06-21 17:19:12 +05:30
1. Follow the [instructions for new projects](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#creating-a-new-project).
1. Follow the instructions for setting up a [CI/CD configuration](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#cicd-configuration).
1. Follow the instructions for [publishing a project](https://about.gitlab.com/handbook/engineering/gitlab-repositories/#publishing-a-project).
2022-08-27 11:52:29 +05:30
- See [issue #325463](https://gitlab.com/gitlab-org/gitlab/-/issues/325463)
2021-06-08 01:23:25 +05:30
for an example.
- In some cases we may want to move a gem to its own namespace. Some
examples might be that it will naturally have more than one project
(say, something that has plugins as separate libraries), or that we
expect non-GitLab-team-members to be maintainers on this project as
well as GitLab team members.
The latter situation (maintainers from outside GitLab) could also
apply if someone who currently works at GitLab wants to maintain
the gem beyond their time working at GitLab.
2022-08-27 11:52:29 +05:30
When publishing a gem to RubyGems.org, also note the section on
[gem owners](https://about.gitlab.com/handbook/developer-onboarding/#ruby-gems)
2021-06-08 01:23:25 +05:30
in the handbook.
2021-03-11 19:13:27 +05:30
## Upgrade Rails
When upgrading the Rails gem and its dependencies, you also should update the following:
- The [`Gemfile` in the `qa` directory](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/Gemfile).
- The [`Gemfile` in Gitaly Ruby](https://gitlab.com/gitlab-org/gitaly/-/blob/master/ruby/Gemfile),
to ensure that we ship only one version of these gems.
You should also update npm packages that follow the current version of Rails:
- `@rails/ujs`
2022-07-23 23:45:48 +05:30
- Run `yarn patch-package @rails/ujs` after updating this to ensure our local patch file version matches.
2021-03-11 19:13:27 +05:30
- `@rails/actioncable`
2021-04-17 20:07:23 +05:30
## Upgrading dependencies because of vulnerabilities
When upgrading dependencies because of a vulnerability, we
should pin the minimal version of the gem in which the vulnerability
was fixed in our Gemfile to avoid accidentally downgrading.
For example, consider that the gem `license_finder` has `thor` as its
dependency. `thor` was found vulnerable until its version `1.1.1`,
which includes the vulnerability fix.
In the Gemfile, make sure to pin `thor` to `1.1.1`. The direct
dependency `license_finder` should already have the version specified.
```ruby
gem 'license_finder', '~> 6.0'
# Dependency of license_finder with fix for vulnerability
# _link to initial security issue that will become public in time_
gem 'thor', '>= 1.1.1'
```
Here we're using the operator `>=` (greater than or equal to) rather
2022-08-27 11:52:29 +05:30
than `~>` ([pessimistic operator](https://thoughtbot.com/blog/rubys-pessimistic-operator))
2021-04-17 20:07:23 +05:30
making it possible to upgrade `license_finder` or any other gem to a
version that depends on `thor 1.2`.
2021-06-08 01:23:25 +05:30
Similarly, if `license_finder` had a vulnerability fixed in 6.0.1, we
2021-04-17 20:07:23 +05:30
should add:
```ruby
gem 'license_finder', '~> 6.0', '>= 6.0.1'
```
This way, other dependencies rather than `license_finder` can
still depend on a newer version of `thor`, such as `6.0.2`, but would
not be able to depend on the vulnerable version `6.0.0`.
A downgrade like that could happen if we introduced a new dependency
2021-06-08 01:23:25 +05:30
that also relied on `thor` but had its version pinned to a vulnerable
2021-04-17 20:07:23 +05:30
one. These changes are easy to miss in the `Gemfile.lock`. Pinning the
version would result in a conflict that would need to be solved.
2022-08-27 11:52:29 +05:30
To avoid upgrading indirect dependencies, we can use
[`bundle update --conservative`](https://bundler.io/man/bundle-update.1.html#OPTIONS).
2021-04-17 20:07:23 +05:30
When submitting a merge request including a dependency update,
include a link to the Gem diff between the 2 versions in the merge request
2022-07-23 23:45:48 +05:30
description. You can find this link on `rubygems.org`, select
**Review Changes** to generate a comparison
2021-04-17 20:07:23 +05:30
between the versions on `diffend.io`. For example, this is the gem
2022-08-27 11:52:29 +05:30
diff for [`thor` 1.0.0 vs 1.0.1](https://my.diffend.io/gems/thor/1.0.0/1.0.1). Use the
2021-04-17 20:07:23 +05:30
links directly generated from RubyGems, since the links from GitLab or other code-hosting
platforms might not reflect the code that's actually published.