Bootstrap version updates

Bootstrap is the CSS/JS framework which is the basis for OBS's UI. The major versions of the framework tend to introduce a lot of breaking changes, that make it difficult to upgrade it. This page aims to point you in the right direction on how to upgrade Bootstrap to the next release without subjecting the rest of the team to reviewing a huge set of changes in a single PR, based on the way we ended up upgrading Bootstrap 4.6 to Bootstrap 5.2.

0. Let your team know

Don't do this unless everyone around you know you are doing it. People need to know that they will have to adjust newly introduced code in the time of transition between versions. So your team has to know you are doing this.

1. Preparing the plan

This is a good first step, you need to learn about the changes that occurred between the versions. Have a look into the migration guide, dive into the Bootstrap codebase to see how the code was restructured and updated. If you have specific class names or function names (for both SCSS and JS) that changed, you need to git grep through the OBS codebase to see which of the changes apply to the update you are going to perform. Feel free to copy the migration guide and remove the parts that don't apply, and note down how many lines the git greps returned, in order to know what impact every change will have. It will make your job easier.

2. Preparing the shims

This is much easier if you do it in one go instead of trying to modify CSS and HTML at the same time. Prepare the CSS classes with names from the newer version of Bootstrap, using the code from the old Bootstrap version. This will function as our shim between the new version and the old version, so that we can use class names from newer version of Bootstrap while using the old version.

2.1 Simple shim example

Let's take #13628 as an example. Upstream changed .no-gutters class to .g-0, so a shim is a matter of using @extend function in the new class name as follows:

.g-0 { @extend .no-gutters; }

2.2 Complex shim example

Let's take #13625 as an example. Upstream changed the padding and margin classes from .m{l,r} and .p{l,r} to .m{s,e} and .p{s,e}. Bootstrap 4 SCSS for generating margin and padding classes, taken from https://github.com/twbs/bootstrap/blob/v4-dev/scss/utilities/_spacing.scss#L5-L29, was as follows (truncated for the example):

@each $breakpoint in map-keys($grid-breakpoints) {
  @include media-breakpoint-up($breakpoint) {
    $infix: breakpoint-infix($breakpoint, $grid-breakpoints);

    @each $prop, $abbrev in (margin: m, padding: p) {
      @each $size, $length in $spacers {
        .#{$abbrev}r#{$infix}-#{$size} {
          #{$prop}-right: $length !important;
        }
        .#{$abbrev}l#{$infix}-#{$size} {
          #{$prop}-left: $length !important;
        }
      }
    }
  }
}

All that needs to be done to this is changing l to s and r to e, as follows:

@each $breakpoint in map-keys($grid-breakpoints) {
  @include media-breakpoint-up($breakpoint) {
    $infix: breakpoint-infix($breakpoint, $grid-breakpoints);

    @each $prop, $abbrev in (margin: m, padding: p) {
      @each $size, $length in $spacers {
        .#{$abbrev}s#{$infix}-#{$size} {
          #{$prop}-right: $length !important;
        }
        .#{$abbrev}e#{$infix}-#{$size} {
          #{$prop}-left: $length !important;
        }
      }
    }
  }
}

For most cases, this is overkill, and so you should follow the simple example instead.

2.5. Unshimmable

Write down the things you weren't able to shim, as well as js changes together, we will come back to those.

3. Group the changes together

Now that you know the impact and how the shims look like, you will have much easier time trying to group the changes together into something that's possible to review by your team. Try not to exceed 100 changed lines, unless you have a very good reason to change things together.

4. Prepare commits

Now that you have grouped everything, prepare the commits in a branch per group. Start out with committing the relevant shim/s of the group, noting the link to the relevant Bootstrap migration guide anchors, as well as link to the Bootstrap codebase from where you may have taken the code in the commit message. Then prepare and commit changes to the HTML. For some of those it's possible to use sed, to make it quicker to modify many files at once. Make sure to verify you didn't make a mistake there.

4.5. Handling unshimmable

After you are done with everything you could shim, you will have to prepare a branch in which you will upgrade Bootstrap, and make the remaining changes to the codebase. Split those changes into smaller commits, to still make it easier to review them.

5. Submit PRs

Push the branches to GitHub, and start creating PRs. You should also mention the links you did in shim commits, to make it easier to review for the rest of your team. After some of the PRs are merged, you will have to rebase other ones, since the classes sometimes are used in the same line, so watch diligently as things are merged.