Skip to content

Upgrade Bootstrap 3 to 4

Summary

Upgrading from Bootstrap 3 to 4 could enable us to start using Bootstrap Vue in our upcoming deliverables.

Advantages

  • Frontend team can consistently use Bootstrap templates in Vue. This should moderately accelerate development speed. The longer csslab takes, the more advantageous this becomes
  • Csslab can be written in Bootstrap 4 and not have to go through a migration from Bootstrap 3 to 4
  • Potentially easier to refactor components in GitLab CE/EE as csslab is built because bootstrap templates should be more consistent with the use of Bootstrap Vue.

Disadvantages

  • Upgrading from Bootstrap 3 to 4 before csslab is fully implemented could lead to regressions because this is a major upgrade. A MR upgrade will be difficult to accurately review
  • Without csslab fully implemented before the upgrade means our CSS is still in constant flux because of incoming MRs being merged, this could make it more difficult to check if something (that is only supported in Bootstrap 3) gets merged during the migration window

Migration checklist

Upgrade scss

  • Polyfill bootstrap 3 variables that are referenced in app/assets/stylesheets/framework/**/*.scss
    • Replace $gray with color("gray") in matching scss
    • Replace .label-inverse with background-color: $label-inverse-bg property in matching scss
  • Run migration script https://gitlab.com/ClemMakesApps/upgrade-bootstrap4 that converts scss selectors loosely based on the list found in http://upgrade-bootstrap.bootply.com/
  • Check for instances with .form-horizontal as it is removed in Bootstrap 4
  • .item should change to .carousel-item (we don't use carousels)
  • .col-*-offset-* should change to .offset-*
  • .col-*-push-* should change to .order-*-2
  • .col-*-pull-* should change to .order-*-1
  • Remove deprecated mixins (user-select, transition-property)

Upgrade CSS class names used in generated HTML (HAML, Vue, JS, Ruby helpers)

  • Typography
    • .page-header- dropped (1 haml occurrence)
    • .dl-horizontal - dropped (no occurrences found)
    • <blockquote> to .blockquote (2 haml occurrences)
  • Grid
    • .col-xs-* to .col-* (73 occurrences)
    • .col-*-offset-* to offset-* (E.g. col-md-offset-1 to offset-md-1) Replace col\-(sm|xs|md|lg)\-offset\-(\d+) with offset-${1}-${2}
    • .col-*-push-* - dropped (in favor of flexbox utility classes such as order-*) (4 matches found)
    • .col-*-pull-* - dropped (in favor of flexbox utility classes such as order-*) (2 matches found)
  • Buttons
    • .btn-default to .btn-secondary
    • .btn-xs - dropped (We can replace with .btn-sm to keep similar size)
  • Button group
    • .btn-group-justified to btn-group.d-flex
    • .btn-group-xs - dropped (Use btn-group-sm) (none found)
  • Breadcrumbs
    • .breadcrumb > li to .breadcrumb > li.breadcrumb-item
  • Carousel (we have no carousels)
    • .next to .carousel-item-next
    • .prev to .carousel-item-prev
    • .left to .carousel-item-left
    • .right to .carousel-item-right
    • .carousel-control.right to .carousel-control-right
    • .carousel-control.left to .carousel-control-left
  • Dropdowns
    • .divider to .dropdown-divider
    • <span class="caret"></span> to dropped (override automatic placement of caret)
    • Dropdown items now require .dropdown-item (ignore for now, since it doesn't seem to make much of a difference)
  • Forms
    • .radio-inline - dropped (None found)
    • .checkbox-inline - dropped (None found)
    • .form-horizontal - dropped (We can use <div class="form-group row"> instead for horizontal forms)
    • .control-label to .col-form-label
    • .input-lg to .form-control-lg (None found)
    • .input-sm to .form-control-sm
    • .form-group-* to .form-control-* (None found)
    • .help-block to .form-text.text-muted
    • .has-error, .has-warning to :invalid (None found)
    • .has-success to :valid (None found)
    • .has-error to .has-danger (None found)
    • .radio to .form-check (be careful of f.radio_button ruby helper)
    • .checkbox to .form-check
    • .form-control-static to .form-control-plaintext
  • Helper classes
    • .center-block to mx-auto
    • .pull-left to float-left
    • .pull-right to float-right
    • .visible-xs-* to .d-block.d-sm-none
    • .visible-sm-* to .d-block.d-md-none
    • .visible-md-* to .d-block.d-lg-none
    • .visible-lg-* to .d-block.d-xl-none
    • .hidden-xs-up to .d-none
    • .hidden-sm-up to .d-sm-none
    • .hidden-md-up to .d-md-none
    • .hidden-lg-up to .d-lg-none
    • .hidden-xl-up to .d-xl-none
  • Images
    • .img-responsive to .img-fluid
    • .img-rounded to .rounded (None found)
    • .img-circle to .rounded-circle (None found)
  • Input groups
    • .input-group-addon to .input-group-prepend, .input-group-append (don't forget to nest content in <div class="input-group-text">)
    • .input-group-btn to .input-group-prepend, .input-group-append (Place .input-group-text for the actual button class to prevent weird padding issues)
  • Labels & Badges
    • .label to .badge (f.label is a rails thing, reminder not to replace that, don't replace label-light, it is a preexisting bad css name that is used for styling labels in forms)
    • .badge to .badge.badge-pill
    • .badge-default to .badge-secondary
  • Navbar
    • .navbar-default to .navbar-light (None found)
    • .navbar-toggle to .navbar-toggler
    • .navbar-form to .form-inline (1 occurrence)
    • .navbar-btn to .nav-item (None found)
    • .navbar-right to .ml-auto (None found)
    • .navbar-left to .mr-auto (None found)
    • .navbar-fixed-top to .fixed-top (1 occurrence)
  • Navs
    • .nav > li to .nav > li.nav-item
    • .nav > li > a to .nav > li.nav-item > a.nav-link
  • Pagination
    • .pagination > li to .pagination > li.page-item
    • .pagination > li > a to .pagination > li.page-item > a.page-link
  • Panels
    • .panel to .card
    • .panel-default - dropped (No replacements)
    • .panel-group to .card-group (None found)
    • .panel-heading to .card-header
    • .panel-title to .card-title
    • .panel-body to .card-body
    • .panel-footer to .card-footer (None found)
    • .panel-primary - bg-primary
    • .panel-success - bg-success
    • .panel-info - bg-info
    • .panel-warning - bg-warning
    • .panel-danger to .bg-danger
    • .panel-footer to .card-footer
  • Wells (Same as panels)
    • .well to .card (Converted some and ported some of the classes)
  • Progress
    • .progress-bar-* to .bg-
    • .active to .progress-bar-animated
  • Tables
    • .table-condensed to .table-sm
    • .active to .table-active
    • .success to .table-success
    • .info to .table-info
    • .warning to .table-warning
    • .danger to .table-danger
  • GitLab Specific
    • .hide to .d-none (134 estimated instances of hide in *.html.haml)
    • .hidden to .d-none (218 estimated instances of hidden in *.html.haml, probably more in other files)
    • .hidden-xs to .d-none .d-sm-block (128 instances of hidden-xs)
    • .hidden-sm to .d-sm-none .d-md-block (37 instances of hidden-sm)
    • .hidden-md to .d-md-none .d-lg-block (9 instances of hidden-md)
    • .hidden-lg to .d-lg-none .d-xl-block (11 instances of hidden-lg)
    • .hidden-xl to .d-xl-none (0 instances of hidden-xl)
    • .visible-*
    • Check instances of form horizontal changes (https://gitlab.com/gitlab-org/gitlab-ce/issues/45185#note_68186346)
    • Check popovers, they dont seem to be working (http://getbootstrap.com/docs/4.1/components/popovers/#overview) (See section below for gitlab specific bugs)
    • Pagination is not working
    • Fix navbar display
    • Fix .card class collision from issue boards https://gitlab.com/gitlab-org/gitlab-ce/issues/45185#note_68201251
    • Fix tooltips
    • Fix dropdowns (See section below for gitlab specific bugs)
  • Override bootstrap's colors (Added to section below)
    • links
    • pagination
    • Flash alert message
  • jQuery specific
    • Replace toggle() as that uses the deprecated .hide class

GitLab specific bugs found

  • Some tooltip arrows are not appearing (timeago)
  • Tooltip on activity page keeps blinking on and off
  • dropdown buttons with tooltips do not dismiss after clicking the dropdown button
  • Unable to load blob
  • PGP popover not showing
  • new group form is broken
  • remove source branch checkbox in new MR is misaligned
  • commit diff page view file is off centered
  • Hide whitespace changes button is off centered in commit diff page
  • weird white lines in commit diff for untouched lines
  • Double next in pagination
  • issue board list title color
  • issue cards list in add issues modal
  • Promote label to group label modal title arrangement
  • Edit milestone form is broken
  • move issue dropdown is broken
  • close issue/mr dropdown is opened when issue is loaded
  • no schedules scheduling pipeline should have no border
  • Error message on schedule a new pipeline is displayed on load
  • truncated page link ... is clickable
  • Remove bootstrap sass

Reviewed

Please add to this list (if you have the permissions to do so) if you have reviewed the CE MR and what you checked. If you do not have permissions, please create a discussion below and I will update this list. Thank you very much!

  • your name here - description
Edited by Clement Ho