diff --git a/docs/postmortems/0000-00-00-template.md b/docs/postmortems/0000-00-00-template.md new file mode 100644 index 0000000000..e9862c31c5 --- /dev/null +++ b/docs/postmortems/0000-00-00-template.md @@ -0,0 +1,67 @@ +--- +date: YYYY-MM-DD +authors: spirit-developer +--- + +# Title of Postmortem + +**Summary** + + + +**Impact** + + + +**Root causes**: + + + +**Detection** + + + +**Resolution** + + + +**Action Items** + + + +| Action item | Owner | Issue | +| ----------- | ----- | ----- | + +## Lessons Learned + +**What went well** + +- Item A +- Item B +- Item C + +**What went wrong** + +- Item A +- Item B +- Item C + +**Where we got lucky** + +- Item A +- Item B +- Item C + +## Timeline (all times in CET/CEST) + +2024-01-01 + +- 14:51 Ipsum reprehenderit impedit facere explicabo fugiat. + +## Supporting Information + + diff --git a/docs/postmortems/2024-02-05-deprecated-icon-rendering.md b/docs/postmortems/2024-02-05-deprecated-icon-rendering.md new file mode 100644 index 0000000000..83ee0ef968 --- /dev/null +++ b/docs/postmortems/2024-02-05-deprecated-icon-rendering.md @@ -0,0 +1,131 @@ +--- +date: 2024-02-05 +authors: @literat +--- + +# Excessive Deprecation Logging While Rendering Icon Component + +**Summary** + + + +The `@lmc-eu/spirit-web-react@1.7.0` is shipped with a new deprecation warning about the `Icon` component. +This deprecation caused massive logging in the browser console and server logs for every other component that used Icon component in it. + +**Impact** + + + +The teams that used the `@lmc-eu/spirit-web-react@1.7.0` and above were impacted by this deprecation warning. +Since many components are using the `Icon` component, the impact were extensive in warning messages that appeared in error logs both in browser developer tools and in the server logs. + +**Root causes**: + + + +These deprecations should have solved the problem with server-side rendering in the Next.js framework where the Icons were not rendered properly. +The deprecation warning was added to the `Icon` component to inform the developers that the `Icon` component will use the `html-react-parser`. +A developer should have installed this dependency to make the `Icon` component work properly. +This dependency should have parsed included SVG and rendered them directly to the DOM. +After this, the usage of the `dangerouslySetInnerHTML` will be obsolete. +For the condition of whether to use the `Icon` rendered by `html-react-parser` or the `dangerouslySetInnerHTML` a new utility called `htmlParser` was created which dynamically imported the library and returned the function or nothing. +This solution was not working properly. +Also, the deprecation warning appeared in all usages of the `Icon` component, no matter the implementation used. + +**Detection** + + + +This problem was detected multiple times by the developers and the support question was raised in our Slack channel: + +- https://almamedia.slack.com/archives/C068XPSDWQN/p1703704125308169 +- https://almamedia.slack.com/archives/C068XPSDWQN/p1707125126127969 +- https://almamedia.slack.com/archives/C068XPSDWQN/p1707215641782159 + +Also, the message appeared in the browser console and the server logs: + +``` +Warning: Icon component is not supported in SSR without use of `html-react-parser`. Please install missing peer dependency. +``` + +**Resolution** + + + +1. The deprecation warning was removed as unnecessary to remove that excessive logging. +2. The `html-react-parser` was added as a regular dependency. +3. The part of the `Icon` component which uses the `dangerouslySetInnerHTML` was removed. + +**Action Items** + + + +| Action item | Owner | Bug | +| ------------------------------ | -------- | ---------------- | +| Remove the deprecation warning | @literat | [#1266][pr-1266] | +| Require HTML parser | @literat | [#1272][pr-1272] | + +## Lessons Learned + +**What went well** + +- We have dealt with this problem multiple times so we have a good idea of what is causing the problem. +- The product teams were able to quickly identify the problem and raise the question in the Slack channel. + +**What went wrong** + +- The lack of testing of the integration of the `html-react-parser` as dynamically imported dependency and the `Icon` component. +- A little awareness of how extensively is the `Icon` component used in our components and the product components. +- We were adding multiple dependencies as peer dependencies and thought that the developers would deal with the installation. + Instead, the regular dependency should be added. The regular dependency is not a part of the bundle unless we set it. + We were trying to use as less dependencies as possible, however in this case it was not the best approach.` + We have cared a lot about the bundle/package size. + +**Where we got lucky** + +- Usage of the `warning` utility everywhere the deprecation is raised and the condition about the `production` environment ensures that the deprecation messages are raised only in the development environment. + +## Timeline (all times in CET/CEST) + +2023-12-27 + +- 20:08 First time spotted a problem with the SSR rendering of the Icon. + +2024-01-10 + +- 11:46 Added the deprecation warning to the `Icon` component. + +2024-02-05 + +- 10:25 Raised support question in the Slack channel. +- 11:34 Raised another support question in the Slack channel. + +2024-02-06 + +- 12:24 @pavelklibani started to work on the support question +- 13:08 The new issue was added by @literat to the ticketing system - [DS-1145][issue-1145] +- 15:56 @literat came with the first version of the solution + +2024-02-07 + +- 09:31 The solution was tested by @janicekt +- 13:59 @literat had a call with @janicekt and agreed on the solution +- 16:04 @literat merged PR [#1266][pr-1266] +- 16:24 `@lmc-eu/spirit-web-react@1.12.0` was released + +## Supporting Information + + + +Commit introducing the problematic deprecation warning: [79f9f6f][commit-79f9f6f] +PR containing the problematic deprecation warning: [#1200][pr-1200] + +[commit-79f9f6f]: https://github.com/lmc-eu/spirit-design-system/commit/79f9f6f207c87296c0c5af1d6c521f48f73206eb +[issue-1145]: https://jira.almacareer.tech/browse/DS-1145 +[pr-1200]: https://github.com/lmc-eu/spirit-design-system/pull/1200 +[pr-1266]: https://github.com/lmc-eu/spirit-design-system/pull/1266 +[pr-1272]: https://github.com/lmc-eu/spirit-design-system/pull/1272 diff --git a/docs/postmortems/README.md b/docs/postmortems/README.md new file mode 100644 index 0000000000..5e8dffecdb --- /dev/null +++ b/docs/postmortems/README.md @@ -0,0 +1,25 @@ +# Postmortems + +> A postmortem is a written record of an incident, its impact, the actions taken +> to mitigate or resolve it, the root cause(s), and the follow-up actions to +> prevent the incident from recurring. +> +> [Postmortem Culture: Learning from failure][learning-from-failure], +> _Devin Carraway_ + +For a full overview, check out the [Software Reliability Engineering book][sre-book] on this +topic. + +## Process + +- Copy the [Postmortem template][postmortem-template] over to a new file +- This file should be named: `YYYY-MM-DD-title.md` + - For example: `2023-11-05-critical-layout-breaking-change.md` +- Fill out the template as best you can, be as detailed as needed +- Submit a Pull Request to the project, make sure to include anyone involved in + the incident as a reviewer so they can provide additional perspectives if + needed + +[learning-from-failure]: https://landing.google.com/sre/sre-book/chapters/postmortem-culture/ +[sre-book]: https://landing.google.com/sre/sre-book/chapters/postmortem/ +[postmorem-template]: ./0000-00-00-template.md