From 8fa4e08fdcca4a91d97a23fe66b718f4747524e1 Mon Sep 17 00:00:00 2001 From: Constance Chen Date: Mon, 27 Sep 2021 14:23:49 -0700 Subject: [PATCH 1/3] Add deprecation documentation to EUI wiki --- wiki/deprecations.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 wiki/deprecations.md diff --git a/wiki/deprecations.md b/wiki/deprecations.md new file mode 100644 index 00000000000..3d08308ca1b --- /dev/null +++ b/wiki/deprecations.md @@ -0,0 +1,36 @@ +# Deprecations + +## General deprecation guidelines + +- For all deprecations, we should retain functionality, but mark them in the EUI docs and add them to the [deprecation schedule issue](https://github.com/elastic/eui/issues/1469). +- EUI performs at-will releases, so our deprecation patterns are based on time rather than release number. We provide at least 3 months time to make upgrades, ideally 6. +- We try as often as possible to make this deprecations non-breaking and will only adjust semvar to major when we believe they would cause anything more than a minor visual break. Because of this, we will plan to follow through on deprecation quarterly to avoid creating lots of major bumps. + +## Deprecation notices + +### Sass + +- When deprecating styles or classes, use `@warn` notices to spit output during the build. + +### Javascript + +- For JS, apply console errors on a case by case basis. We've received feedback these can be overly noisy and remove confidence in the end product. + +## Documentation + +### Component props + +- Add prop documentation with `DEPRECATED` in bold, including instructions on what alternative (if any) to use. For example, [see this deprecation comment](https://github.com/elastic/eui/blob/79960490cd27e9f97c05a2bf58d33056d2c66a62/src/components/card/card.tsx#L127). + +### Entire components + +- Add a badge to the documentation page indicating the component is set for deprecation, with an optional additional callout explaining why and what alternatives (if any) users have. For example, [see this component deprecation](https://github.com/elastic/eui/blob/312e2c48c7db62f435d1c65bf2011e31e55cbfa4/src-docs/src/views/accessibility/accessibility_example.js#L71-L91). + +## Actual removal of features + +When it comes to actually removing features: + +- If your component, prop, or utility, is being used internally in EUI, ensure you've removed cases of it where possible prior to the actual deletion date. +- Optionally check for Kibana's usage of the deprecated functionality and contact the appropriate teams to let them know they should look into removing its usage as well as offering alternatives (if any). + +Ideally, when the final deprecation date listed in the schedule comes up, there should be little to no friction involved in simply deleting the entire feature from the codebase as both EUI and Kibana will already have moved off the deprecated feature. From 57a1297dd767d0f586a86dad30ff788eb12cac61 Mon Sep 17 00:00:00 2001 From: Constance Chen Date: Mon, 27 Sep 2021 14:24:35 -0700 Subject: [PATCH 2/3] [misc] Add stylelintrc ignore for markdown documents --- .stylelintrc | 1 + 1 file changed, 1 insertion(+) diff --git a/.stylelintrc b/.stylelintrc index 29fe9b0dd94..bfa7ff79eb1 100644 --- a/.stylelintrc +++ b/.stylelintrc @@ -8,5 +8,6 @@ "**/*.tsx", "**/*.js", "**/*.jsx", + "**/*.md" ] } From 54cd98095ae5a8c1075a9ed00ad133a6afff36e2 Mon Sep 17 00:00:00 2001 From: Constance Date: Tue, 28 Sep 2021 14:30:23 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Caroline Horn <549577+cchaos@users.noreply.github.com> --- wiki/deprecations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/wiki/deprecations.md b/wiki/deprecations.md index 3d08308ca1b..c68db9bd291 100644 --- a/wiki/deprecations.md +++ b/wiki/deprecations.md @@ -20,7 +20,7 @@ ### Component props -- Add prop documentation with `DEPRECATED` in bold, including instructions on what alternative (if any) to use. For example, [see this deprecation comment](https://github.com/elastic/eui/blob/79960490cd27e9f97c05a2bf58d33056d2c66a62/src/components/card/card.tsx#L127). +- Add prop documentation with `**DEPRECATED**` in bold, including instructions on what alternative (if any) to use. For example, [see this deprecation comment](https://github.com/elastic/eui/blob/79960490cd27e9f97c05a2bf58d33056d2c66a62/src/components/card/card.tsx#L127). ### Entire components @@ -31,6 +31,6 @@ When it comes to actually removing features: - If your component, prop, or utility, is being used internally in EUI, ensure you've removed cases of it where possible prior to the actual deletion date. -- Optionally check for Kibana's usage of the deprecated functionality and contact the appropriate teams to let them know they should look into removing its usage as well as offering alternatives (if any). +- Optionally check for known consumer usages of the deprecated functionality and contact the appropriate teams to let them know they should look into removing its usage as well as offering alternatives (if any). Ideally, when the final deprecation date listed in the schedule comes up, there should be little to no friction involved in simply deleting the entire feature from the codebase as both EUI and Kibana will already have moved off the deprecated feature.