From c3736ef9b8b94d3c14f409fff7be1535e78e88a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mikel=20Mart=C3=ADn?= Date: Wed, 28 Feb 2024 13:49:26 +0100 Subject: [PATCH] [docs] Move Bootstrap 5 migration to a new page --- docs/devupdate.md | 102 +--------------------- docs/guides/bs5migration/index.md | 137 ++++++++++++++++++++++++++++++ 2 files changed, 139 insertions(+), 100 deletions(-) create mode 100644 docs/guides/bs5migration/index.md diff --git a/docs/devupdate.md b/docs/devupdate.md index b453e34496..2ba8d07567 100644 --- a/docs/devupdate.md +++ b/docs/devupdate.md @@ -237,111 +237,13 @@ shortname,fullname,category,summary,cohort,student,cohort,teacher -## Bootstrap preparations for version 5 +## Refactoring BS4 features dropped in BS5 Some of the Bootstrap 4 classes will be deprecated or dropped in its version 5. To prepare for this, some of the current Bootstrap 4 classes usages have been replaced with version 5 compatible classes. This will help us to upgrade to Bootstrap 5 in the future. -### Badges - -- Badge colour class helpers `.badge-*` have been replaced with background utilities (use `.bg-primary` instead of `.badge-primary`) combined with the corresponding text colour classes (`.text-dark` or `.text-white`) to meet accessibility contrast. -- The `.badge-pill` class has been replaced with `.rounded-pill` - - - -```html -Error badge -``` - - - - - -```html -Error badge -``` - - - -### Media - -The `.media` component has been replaced with utility classes. - - - -```html -
-
- [...] -
-
- [...] -
-
-``` - - - - - -```html -
-
- [...] -
-
- [...] -
-
-``` - - - -### Mixins - -The following previously deprecated mixins will be dropped in BS5, so they can be refactored: - -- hover, hover-focus, plain-hover-focus and hover-focus-active -- float-left, float-right and float-none -- nav-divider -- img-retina -- text-hide -- invisible -- form-control-focus -- text-emphasis-variant -- size -- make-container-max-widths -- g-variant and bg-gradient-variant - - - -```css -.collapse-list-item { - padding: $collapse-list-item-padding-y $collapse-list-item-padding-x; - @include hover-focus() { - background-color: $collapse-list-item-hover-bg; - border-color: $collapse-list-item-hover-border; - } -} -``` - - - - - -```css -.collapse-list-item { - padding: $collapse-list-item-padding-y $collapse-list-item-padding-x; - &:hover, - &:focus { - background-color: $collapse-list-item-hover-bg; - border-color: $collapse-list-item-hover-border; - } -} -``` - - +See more information in [Bootstrap 5 migration](./guides/bs5migration/index.md). ## New course section page diff --git a/docs/guides/bs5migration/index.md b/docs/guides/bs5migration/index.md new file mode 100644 index 0000000000..e1df2842df --- /dev/null +++ b/docs/guides/bs5migration/index.md @@ -0,0 +1,137 @@ +--- +title: Bootstrap 5 migration +tags: +- Bootstrap +--- + + + +import { + Since, + ValidExample, + InvalidExample, +} from '@site/src/components'; + +Bootstrap 5 has evolved with new features, improvements, and changes in its latest version, and along with this some breaking changes also come, which need to be addressed in the migration process. + +:::info + +See more about Bootstrap 5 breaking changes in the [official documentation](https://getbootstrap.com/docs/5.0/migration/). + +::: + +To achieve a smoother process and facilitate the moment of the update, the migration has been divided into different steps: + +1. **PopperJS upgrade**: This is the first step in the migration process, as Bootstrap 5 requires PopperJS version 2. This step is about upgrading the current PopperJS version to version 2. Because we still need PopperJS version 1 for Bootstrap 4 both versions will co-exist until all usages are migrated to v2. +2. **SCSS Deprecation process**: A SCSS deprecation process will be needed for the cleanup after BS5 upgrade. More details about it in [SCSS deprecation](../../general/development/policies/deprecation/scss-deprecation). +3. **Refactoring BS4 features dropped in BS5**: This step is about refactoring the current Bootstrap 4 features that will be deprecated or dropped in its version 5 and they can be replaced with current codebase. +4. **Create a BS5 "bridge"**: Some simple breaking changes could be also addressed in advance creating a BS5 "bridge". With small additions to this "bridge", we can refactor in advance the occurences in the codebase for some dropped features in BS5. +5. **BS5 upgrade**: Upgrade the current Bootstrap 4 version to version 5. +6. **BS4 backwards-compatibility layer**: Alongside the update, a new backwards-compatibility layer will also be created, and some of the Bootstrap 4 syntax will still work until the final deprecation. This will help third-party plugins to be updated in a more gradual way. +7. **Final deprecation** + +## Refactoring BS4 features dropped in BS5 + + + +Some of the Bootstrap 4 classes will be deprecated or dropped in its version 5. To prepare for this, some of the current Bootstrap 4 classes usages have been replaced with version 5 compatible classes. Doing these refactors in advance, will help us to upgrade to Bootstrap 5 in the future. + +### Badges + +- Badge colour class helpers `.badge-*` have been replaced with background utilities (use `.bg-primary` instead of `.badge-primary`) combined with the corresponding text colour classes (`.text-dark` or `.text-white`) to meet accessibility contrast. +- The `.badge-pill` class has been replaced with `.rounded-pill` + + + +```html +Error badge +``` + + + + + +```html +Error badge +``` + + + +### Media + +The `.media` component has been replaced with utility classes. + + + +```html +
+
+ [...] +
+
+ [...] +
+
+``` + + + + + +```html +
+
+ [...] +
+
+ [...] +
+
+``` + + + +### Mixins + +The following previously deprecated mixins will be dropped in BS5, so they can be refactored: + +- hover, hover-focus, plain-hover-focus and hover-focus-active +- float-left, float-right and float-none +- nav-divider +- img-retina +- text-hide +- invisible +- form-control-focus +- text-emphasis-variant +- size +- make-container-max-widths +- g-variant and bg-gradient-variant + + + +```css +.collapse-list-item { + padding: $collapse-list-item-padding-y $collapse-list-item-padding-x; + @include hover-focus() { + background-color: $collapse-list-item-hover-bg; + border-color: $collapse-list-item-hover-border; + } +} +``` + + + + + +```css +.collapse-list-item { + padding: $collapse-list-item-padding-y $collapse-list-item-padding-x; + &:hover, + &:focus { + background-color: $collapse-list-item-hover-bg; + border-color: $collapse-list-item-hover-border; + } +} +``` + +