Deprecation Period

[emplums]

Now that Primer Components is becoming more mature of a library, we should consider implementing a deprecation period for components and/or props when we want to make breaking changes. Doing so would allow us to make important API improvements, without causing too much of a disruption of workflows for our users (or at least soften the impact a bit).

How would we want to go about implementing this? Console warnings? Would we add the deprecation notice before we make any changes to the API, or would we make the change but keep the old API for a period of time + add the notice, and then remove the notice when we remove the backwards compatibility?

Drawbacks:

• deprecation notices might just be more work/mental load?
• adds a bit of process & maintenance overhead

Curious what other folks think, especially those of you who have worked on large design systems at other companies! :)

[BinaryMuse]

I agree that a deprecation period of breaking changes might be a good thing for the library.

How would we want to go about implementing this? Console warnings? Would we add the deprecation notice before we make any changes to the API, or would we make the change but keep the old API for a period of time + add the notice, and then remove the notice when we remove the backwards compatibility?

The problem with adding deprecation notices before making changes to the API is that the deprecation notice isn't actionable; you have to wait for the change to come down the pipeline and break your app, and only then can you make the change. I think it's better to make the API change so that people can see the deprecation notice, change to the new API, and be confident that they're ready to update to the next version.

The downside to this is that some of our changes might be difficult to implement like this. Looking back at some of our recent breaking changes:

• Removed "Segoe UI Symbol" from font stack as it is not compatible with Chinese characters — not sure about this one, maybe add some sort of option, or perhaps a copy of the theme with/without the font included during the deprecation period?
• BorderBox has had its default border prop split into borderWidth and borderStyle — a tricky one, not certain off the top of my head how we'd handle this one.
• Dialog components no longer render with a header by default — we could continue to detect the title attribute and automatically add the Dialog.Header attribute and log a warning
• Heading now renders an h2 by default instead of an h1 — another one that seems tricky
• Dropdown elements no longer provide a dropdown button by default — not super obvious, but perhaps we could iterate over the children and try to determine if the user has included a Dropdown.Button or some other element that renders as a summary

[BinaryMuse]

Closed by #777 and #791