Create deprecating-components.md #2733

broccolinisoup · 2023-01-03T03:43:00Z

Closes https://github.com/github/primer/issues/1593

This PR is based on deprecating React components ADR , my notes from chatting with PRC folks about the process as well as my first time deprecating a component experience. So this is a pretty much raw document that I would love to get your thoughts on 🙏🏼

Note: I copy-pasted quite a few info from the ADR, thanks to @siddharthkp :)

Take a look at the What we look for in reviews section of the contributing guidelines for more information on how we review PRs.

changeset-bot · 2023-01-03T03:43:03Z

⚠️ No Changeset found

Latest commit: e6b6bb2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2023-01-03T03:46:22Z

size-limit report 📦

Path	Size
dist/browser.esm.js	94.5 KB (0%)
dist/browser.umd.js	95.08 KB (0%)

contributor-docs/deprecating-components.md

broccolinisoup · 2023-01-03T10:10:47Z

contributor-docs/deprecating-components.md

+
+## Developing a draft component
+
+Start building the new component outside of the main bundle. This includes the source code of the component being under the `src/drafts` folder and the component being exported in the draft bundle (`src/drafts/index.ts`). That way, folks who


I see some of the drafts component under the src/drafts and some not. Would that be true that we eventually want to have the practise to create the drafts components under the src/drafts?

@siddharthkp instead of recommending these components go into src/drafts, do you think we should be encouraging folks to build directly in the new experimental components repo instead? https://github.com/github/experimental-react-components

Oh super keen to hear about this 👀

Yes!

But given the change in direction for experimental-components, i'm not sure if it should be github/experimental-react-components or our own primer/react-experimental, another ADR? 😅

Yes, probably. @justinbyo is going to be helping us figure out ownership models for shared React components looking forward.

In the meantime, are we comfortable shipping these docs with the direction to build direct in experimental-react-components for now, and we can always update if/when we make a change? We don't seem to deprecate components super often so I'm thinking that changing this guidance later wouldn't be a huge problem.

Good point @broccolinisoup. In most cases we should have similar standards for components (including unit tests and Storybook) in the experimental-react-components repo as we do in primer/react. I'm admittedly not as familiar with all of the items in the checklist and whether they would apply exactly the same in experimental-react-components; what do you think @siddharthkp?

In most cases we should have similar standards for components (including unit tests and Storybook) in the experimental-react-components repo as we do in primer/react

I am a fan of this!

I wasn't sure how much we can "influence" experimental-react-components to follow our Primer component standards.
From my observation, experimental-react-components differ from PRC in the way of documenting components and they don't include some util unit test functions as PRC do.

Super keen to hear @siddharthkp's thoughts.

👋 thanks for DMing me! i've lost the fight against notifications.

I wasn't sure how much we can "influence" experimental-react-components to follow our Primer component standards.

Oooh, we definitely should influence it a lot. We can even assist (and enforce) practices by baking them into the react toolchain.

However, we also keep the barrier for contribution pretty low. Experimental components are meant to be pre-alpha in the lifecycle, more context in ADR 008

From my observation, experimental-react-components differ from PRC in the way of documenting components and they don't include some util unit test functions as PRC do.

Some of this, like the docs, is intentional, we chose storybook docs over doctocat to make it easier (and less elaborate) to document than primer. The lack of test functions isn't part of the strategy, that's just because we've only had one iteration of this till now :)

Oooh, we definitely should influence it a lot. We can even assist (and enforce) practices by baking them into the react toolchain.

Awesome to hear!

However, we also keep the barrier for contribution pretty low. Experimental components are meant to be pre-alpha in the lifecycle, more context in ADR 008

This is a pretty good point!

Some of this, like the docs, is intentional, we chose storybook docs over doctocat to make it easier (and less elaborate) to document than primer. The lack of test functions isn't part of the strategy, that's just because we've only had one iteration of this till now :)

Gotcha!

It feels to me that moving experimental components from react-experimental-components is a slightly different process than deprecating components, especially around the practises.

Another question - if an existing component was to be re-written by a Primer engineer (following all Primer standards), would we still start in the experimental-react-components repo or in our own repos?

cc @lesliecdubs

Hello! @siddharthkp and @lesliecdubs

Seems like we still have questions regarding to experimental-react-components repo's practises and how they will make their way to Primer. Would it be okay to go ahead with this section as is (creating the components in the drafts folder) until we have a clear practise for experimental-react-components? At least we will treat this document as the current practise and we can update as we go?

contributor-docs/deprecating-components.md

broccolinisoup · 2023-01-03T10:27:39Z

contributor-docs/deprecating-components.md

+
+Once the major release is out, we provide support on how to switch using the newly develop component as well as how to continue to use the deprecated component for folks who prefer to migrate later on.
+
+We also write codemods to deprecate the old component and use the new component under [our migration repo](https://github.com/primer/react-migrate#readme).


Do we provide any other support for teams except proving these codemods? Do they actually go and update the usages themselves or do we do it?

Also, is there any other practise we do or would like to introduce to encourage teams switching using the new components?

lesliecdubs

Thank you so much for writing this up!

contributor-docs/deprecating-components.md

lesliecdubs · 2023-01-03T19:25:19Z

contributor-docs/deprecating-components.md

+
+## Developing a draft component
+
+Start building the new component outside of the main bundle. This includes the source code of the component being under the `src/drafts` folder and the component being exported in the draft bundle (`src/drafts/index.ts`). That way, folks who


@siddharthkp instead of recommending these components go into src/drafts, do you think we should be encouraging folks to build directly in the new experimental components repo instead? https://github.com/github/experimental-react-components

contributor-docs/deprecating-components.md

Co-authored-by: Leslie Cohn-Wein <lesliecdubs@github.com>

joshblack

Looks great! I feel like this documents my understanding of the current deprecation process 👍 Just left a grammar suggestion and a note on the FAQ 👀

contributor-docs/deprecating-components.md

joshblack · 2023-01-13T19:13:00Z

contributor-docs/deprecating-components.md

+## FAQ
+
+- Does the deprecated component accept new feature request?
+  - No, because we have a single bundle for all components, you can not pick the components you want to upgrade. This can result in additional unrelated work.


Might be helpful to highlight that, once deprecated, the component is likely in a "maintenance mode" and will only receive bug fixes. Maybe something like:

Suggested change

- No, because we have a single bundle for all components, you can not pick the components you want to upgrade. This can result in additional unrelated work.

- No, once a component is deprecated the only changes it will receive are bug fixes.

What do y'all think: should this be will receive or may receive? Not sure how dedicated we've been to handling all bugfixes in deprecated components, or just major functional bugs 🤔

"may receive" sounds good to me. I like that it removes the certainty.

I updated to be "may receive" but please let me know if anyone has a concern 🙌🏻

broccolinisoup · 2023-01-27T10:32:56Z

contributor-docs/deprecating-components.md

+
+### Comms side of the deprecation
+
+When Primer team is ready to promote the newly developed component in the main bundle and the component v1 is good to be deprecated in the next major release, team announces the deprecation and the promotion in the [Primer changelog](https://github.com/github/primer/discussions/categories/primer-changelog) (GitHub staff only) under the `Coming soon` section and release a technical preview. Please see an example of the [technical preview announcement for the v35](https://github.com/primer/react/discussions/1918).


I updated this section to reflect @rezrah's comments on versioning docs ✨

broccolinisoup · 2023-01-31T09:28:19Z

contributor-docs/deprecating-components.md

@@ -0,0 +1,91 @@
+# Deprecating and promoting components in Primer React


I am not sure if "Promoting" a good word for describing the process to move the deprecated component into the deprecated bundle. I thought it would be good to separate the process of deprecation (as in adding a @deprecated annotation) and moving the component into the deprecated folder.

cc @colebemis

broccolinisoup · 2023-02-16T04:47:27Z

I'd like to move forward with this PR if that is okay. This reflects the current process - We will need to come back and update the documentation around creating the components under the drafts folder when we have our unstable bundle is renamed to experimental from drafts. (See ADR for reference) Or If we come up with an alternative solution we will need to update this doc. However currently, it all reflects the current process.

@lesliecdubs Since you requested changes before, it needs your approval 😇 Thank you!

broccolinisoup temporarily deployed to github-pages January 3, 2023 03:49 — with GitHub Actions Inactive

github-actions bot temporarily deployed to storybook-preview-2733 January 3, 2023 03:49 Inactive

broccolinisoup added the skip changeset This change does not need a changelog label Jan 3, 2023

broccolinisoup temporarily deployed to github-pages January 3, 2023 04:25 — with GitHub Actions Inactive

github-actions bot temporarily deployed to storybook-preview-2733 January 3, 2023 04:26 Inactive

broccolinisoup temporarily deployed to github-pages January 3, 2023 04:42 — with GitHub Actions Inactive

github-actions bot temporarily deployed to storybook-preview-2733 January 3, 2023 04:43 Inactive

broccolinisoup commented Jan 3, 2023

View reviewed changes

contributor-docs/deprecating-components.md Outdated Show resolved Hide resolved

broccolinisoup temporarily deployed to github-pages January 3, 2023 05:36 — with GitHub Actions Inactive

github-actions bot temporarily deployed to storybook-preview-2733 January 3, 2023 05:37 Inactive

Create deprecating-components.md

aac770b

broccolinisoup force-pushed the bs/deprecating-comp-docs branch from 53927e1 to aac770b Compare January 3, 2023 05:40

broccolinisoup temporarily deployed to github-pages January 3, 2023 05:46 — with GitHub Actions Inactive

github-actions bot temporarily deployed to storybook-preview-2733 January 3, 2023 05:46 Inactive

broccolinisoup marked this pull request as ready for review January 3, 2023 05:52

broccolinisoup requested review from a team, josepmartins, colebemis, joshblack, siddharthkp and lesliecdubs January 3, 2023 05:52

broccolinisoup commented Jan 3, 2023

View reviewed changes

contributor-docs/deprecating-components.md Outdated Show resolved Hide resolved

broccolinisoup commented Jan 3, 2023

View reviewed changes

contributor-docs/deprecating-components.md Outdated Show resolved Hide resolved

broccolinisoup commented Jan 3, 2023

View reviewed changes

lesliecdubs requested changes Jan 3, 2023

View reviewed changes

Apply suggestions from code review

5ee2013

Co-authored-by: Leslie Cohn-Wein <lesliecdubs@github.com>

joshblack approved these changes Jan 13, 2023

View reviewed changes

Merge branch 'main' into bs/deprecating-comp-docs

a05470e

joshblack temporarily deployed to github-pages January 25, 2023 16:39 — with GitHub Actions Inactive

github-actions bot temporarily deployed to storybook-preview-2733 January 25, 2023 16:40 Inactive

broccolinisoup mentioned this pull request Jan 27, 2023

docs: add versioning guide #2753

Closed

broccolinisoup added 2 commits January 27, 2023 16:06

Merge branch 'main' into bs/deprecating-comp-docs

d857286

update the docs

be4d425

broccolinisoup temporarily deployed to github-pages January 27, 2023 10:27 — with GitHub Actions Inactive

github-actions bot temporarily deployed to storybook-preview-2733 January 27, 2023 10:27 Inactive

broccolinisoup commented Jan 27, 2023

View reviewed changes

Merge branch 'main' into bs/deprecating-comp-docs

56b0650

broccolinisoup temporarily deployed to github-pages January 27, 2023 22:44 — with GitHub Actions Inactive

github-actions bot temporarily deployed to storybook-preview-2733 January 27, 2023 22:45 Inactive

Merge branch 'main' into bs/deprecating-comp-docs

2811c88

broccolinisoup temporarily deployed to github-pages January 31, 2023 02:50 — with GitHub Actions Inactive

github-actions bot temporarily deployed to storybook-preview-2733 January 31, 2023 02:50 Inactive

rewording deprecation

e97505e

broccolinisoup commented Jan 31, 2023

View reviewed changes

broccolinisoup temporarily deployed to github-pages January 31, 2023 09:33 — with GitHub Actions Inactive

github-actions bot temporarily deployed to storybook-preview-2733 January 31, 2023 09:34 Inactive

broccolinisoup mentioned this pull request Jan 31, 2023

Issue @deprecated notice for the UnderlineNav v1 #2834

Merged

6 tasks

lesliecdubs approved these changes Feb 17, 2023

View reviewed changes

Merge branch 'main' into bs/deprecating-comp-docs

e6b6bb2

broccolinisoup temporarily deployed to github-pages February 17, 2023 03:20 — with GitHub Actions Inactive

github-actions bot deployed to storybook-preview-2733 February 17, 2023 03:21 View deployment

broccolinisoup added this pull request to the merge queue Feb 17, 2023

Merged via the queue into main with commit 46865b8 Feb 17, 2023

broccolinisoup deleted the bs/deprecating-comp-docs branch February 17, 2023 03:48


		## Developing a draft component

		Start building the new component outside of the main bundle. This includes the source code of the component being under the `src/drafts` folder and the component being exported in the draft bundle (`src/drafts/index.ts`). That way, folks who


		Once the major release is out, we provide support on how to switch using the newly develop component as well as how to continue to use the deprecated component for folks who prefer to migrate later on.

		We also write codemods to deprecate the old component and use the new component under [our migration repo](https://github.com/primer/react-migrate#readme).

	- No, because we have a single bundle for all components, you can not pick the components you want to upgrade. This can result in additional unrelated work.
	- No, once a component is deprecated the only changes it will receive are bug fixes.


		### Comms side of the deprecation

		When Primer team is ready to promote the newly developed component in the main bundle and the component v1 is good to be deprecated in the next major release, team announces the deprecation and the promotion in the [Primer changelog](https://github.com/github/primer/discussions/categories/primer-changelog) (GitHub staff only) under the `Coming soon` section and release a technical preview. Please see an example of the [technical preview announcement for the v35](https://github.com/primer/react/discussions/1918).

		@@ -0,0 +1,91 @@
		# Deprecating and promoting components in Primer React

Create deprecating-components.md #2733

Create deprecating-components.md #2733

Uh oh!

Conversation

broccolinisoup commented Jan 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Jan 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented Jan 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

Uh oh!

broccolinisoup Jan 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

siddharthkp Jan 17, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lesliecdubs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

joshblack left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

broccolinisoup Jan 27, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

broccolinisoup commented Feb 16, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

broccolinisoup commented Jan 3, 2023 •

edited

Loading

changeset-bot bot commented Jan 3, 2023 •

edited

Loading

github-actions bot commented Jan 3, 2023 •

edited

Loading

broccolinisoup Jan 3, 2023 •

edited

Loading

siddharthkp Jan 17, 2023 •

edited

Loading

broccolinisoup Jan 27, 2023 •

edited

Loading

broccolinisoup commented Feb 16, 2023 •

edited

Loading