docs(deprecations): add new page including upcoming deprecation details #4301
Conversation
tay1orjones
requested review from
alisonjoseph,
annawen1 and
Kritvi-bhatia17
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
@alisonjoseph Yeah I was surprised too 😱 I'm not opposed to adding it to the nav, just felt 50/50 to me if we'd want it there. Sorta feels like it shouldn't be discoverable, to instead have users hit that page only when they're guided there? Like from the npm deprecation message or the package readme's. What do you think? I also couldn't figure out where we'd want to put it in the left nav 🤔 |
There was a problem hiding this comment.
Amazing idea @tay1orjones! 🔥
I feel the deprecated section shares similarities with the feature flag regarding its timing and importance. Feature flag components become more prominent as a version nears its end, while deprecated components are most significant when a new version is released. The deprecated section will likely gain relevance once v12 is live, as users will start inquiring about which components have been deprecated.
Therefore, it might be a good idea to make this section accessible—either directly or indirectly—via navigation. We could explore potential placements, such as next to the Feature Flag section or under Releases. These are just some initial thoughts!
|
@Kritvi-bhatia17 great points, thanks for bringing them up! These deprecations are slightly different than feature-flag-related deprecations. These docs relate to the larger/more broad package and package version "deprecations" which happen after a package's end-of-support date. These are different from deprecations within the packages (components, functions, etc.). We should discuss and figure out where those "intra-package" deprecations docs should live. I skew towards continuing to document them in situ at the package-level storybook, but maybe there is a place for some kind of content about them on the website. The package and version deprecations here will be immediately relevant on Monday as we'll be doing a formal deprecation on npm for both these packages, as well as v10.x versions of the other One other thing regarding the left nav concern is I think it's beneficial for this url to be as short as possible. We'll be using it in the deprecation message on npm and it will be printed in developer consoles where space is limited. Example: vs |
|
Oh, I see! Got it—thanks a lot, @tay1orjones, for such a detailed explanation. If needed, we can discuss later how to handle feature-flag-related deprecations for both developers and designers. I believe there might already be a section for that on the website, but I’ll need to check; that’s a bit off-topic for now. In any case, you guys have more knowledge and insight on this, will leave it up to y'll! |
There was a problem hiding this comment.
@tay1orjones that makes sense, thinking about it more I don't see a logical place to put it in the left nav. Maybe if we added another layer of navigation in the future under Frameworks we could link to it as a subpage of React, but for now its probably fine as is.
|
@alisonjoseph @annawen1 @Kritvi-bhatia17 I've updated this to include the latest feedback, and also added a section for v10 elements packages and |
tay1orjones
requested review from
kennylam
and removed request for
annawen1
|
I'm just going to leave this comment here since I didn't get it in before the merge. There are some formatting/visual things I would like to fix on this page if we ever make the deprecations page visible in the nav. Just to help with type hierarchy and information processing. |
Derp! Sorry about that. I should have let you have a pass before merging. |
|
@aagonzales sounds good, the main thing I was optimizing for was anchor links per-package so we can deep link for support purposes. Like carbondesignsystem.com/deprecations#carbon-icons for example |
Part of carbon-design-system/carbon#12497
Changelog
New
carbondesignsystem.com/deprecationsfrom the deprecation message that will be visible on npmjs.com as well as developer terminal/consoles when installing the deprecated packages. but let me know what you think!