ADR 010: Merge drafts status into experimental

[siddharthkp]

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

Rendered markdown →

[changeset-bot]

⚠️ No Changeset found

Latest commit: afb1bc8

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]

size-limit report 📦

Path	Size
dist/browser.esm.js	89.74 KB (0%)
dist/browser.umd.js	90.28 KB (0%)

[lesliecdubs]

Thanks for writing this up, @siddharthkp! @primer/react-reviewers please take a look and leave any feedback on this ADR. I will also add a few reviewers who have a stake in our lifecycle criteria and/or who may have context from working on other Primer libraries.

This is a technical decision being made for a product reason, so I think it makes the most sense for @justinbyo to serve as the decision maker.

ADR decision maker: @justinbyo
Decision deadline: EOD February 10, 2023 - let me know if you need more time!

Your role as decision maker is to gather feedback, probe for discussion and disagreement, and then make an informed decision based on the feedback, identified risks, and trade-offs about whether to adopt the ADR or not. Your role is not to decide based on your own personally preferred approach.

Keep in mind that ADR decisions can be reversed or changed in the future if new information is exposed that make the ADR worth revisiting.

You can fulfill your decision maker role by doing the following:

• review the ADR, comments, and feedback closely
• seek additional feedback from any necessary parties, as needed; for example, request a review from any individuals or teams that you know would be unduly affected by this ADR, or who have extensive experience in using either the preferred or non-preferred approach and may have perspective to share about it
• follow up on any remaining concerns, questions, or unexamined risks around accepting the proposed approach
• on or before the deadline, make a decision as to whether the ADR is accepted ✅ , which you should signal by approving this PR, or rejected 🚫 , which you should signal by closing this PR with a comment explaining the reason(s)

[jonrohan]

Great change. I like that it will align better with PVC statuses.

[broccolinisoup]

Thank you so much for writing this up @siddharthkp ✨ I have a few questions

• Would this change affect our practises in PRC, in any way, on creating and releasing components? (Except the path is changing and we will have a bundle with a different name)
• In the component lifecycle docs, it states that experimental components often are built outside of Primer - should we re-write this?

[siddharthkp]

Would this change affect our practises in PRC, in any way, on creating and releasing components? (Except the path is changing and we will have a bundle with a different name)

Nope, this ADR doesn't propose any changes. (I do want to create a different ADR in the future for that 😅)

In the component lifecycle docs, it states that experimental components often are built outside of Primer - should we re-write this?

Yes! Good spot!

[colebemis]

Sounds good to me 👍

[broccolinisoup]

Would this change affect our practises in PRC, in any way, on creating and releasing components? (Except the path is changing and we will have a bundle with a different name)

Nope, this ADR doesn't propose any changes. (I do want to create a different ADR in the future for that 😅)

In the component lifecycle docs, it states that experimental components often are built outside of Primer - should we re-write this?

Yes! Good spot!

Lovely! Thank you 🙌🏻

Also created https://github.com/github/primer/issues/1799 so that we don't forget 😊

[justinbyo]

I very much like the consolidation proposed here. The problem statement is spot-on and I think this solution addresses it well. "Draft" is meaningless to the end consumer, and I like that we're consolidating around the component lifecycle.

@siddharthkp @broccolinisoup Can you clarify what impact this ADR will have on components labelled "experimental" currently built outside of Primer? Specifically, this statement:

In the component lifecycle docs, it states that experimental components often are built outside of Primer - should we re-write this?

I'm concerned this might create confusion because we have "experimental" components, like DatePicker, that are in the experimental-react-components repo. We're not planning to upstream DatePicker yet, so it will remain "experimental" and also outside the Primer lifecycle and ownership for the foreseeable future.

[joshblack]

Definitely makes sense to consider these explorations as experimental 💯

From the side-effects side, I'd separately love to explore alternatives to separate bundles to:

• Reduce the number of total entrypoints
• Provide an easier way to deprecate components, or features of a component
• Provide an easier migration process when moving between versions of a component

Specifically, right now an awkward flow is that in order to deprecate stuff we have to point teams to use a separate entrypoint for a component.

From the consumer side, I think simplifying things into "stable" and "unstable" could help to indicate the stability of an item and our commitment to maintaining its API between minor and patch versions.

[joshblack]

As an alternative, would love to explore other ways of indicating API stability (like through an unstable_* prefix through the main bundle). It would be great to limit the number of entrypoints that we ship, especially if the intent is to have them move to the main entrypoint over time.

[broccolinisoup]

I am loving this proposal! 💖 Even as a maintainer of PRC, it took me a while to wrap my head around this ~ not sure how the experience was for consumer both Hubbers and non Hubber consumers.

[broccolinisoup]

@siddharthkp @broccolinisoup Can you clarify what impact this ADR will have on components labelled "experimental" currently built outside of Primer? Specifically, this statement:
"In the component lifecycle docs, it states that experimental components often are built outside of Primer - should we re-write this?"

I'm curious to hear Sid's thoughts around this. When I wrote my question, I imagined we would be have "Primer" experimental components as well as experimental-react-components repo and I was proposing to update the docs to particularly reword the line of "experimental components often are built outside of Primer" which is not correct anymore and give more context of "Primer" experimental components. @justinbyo

[siddharthkp]

We're not planning to upstream DatePicker yet, so it will remain "experimental" and also outside the Primer lifecycle and ownership for the foreseeable future.

That's totally fine :)

In the docs today, we say "Proof-of-concept, often built outside of Primer". This qualification of outside/inside Primer is unnecessary because we often build experimental components inside Primer as well. 😅

[siddharthkp]

@joshblack

Specifically, right now an awkward flow is that in order to deprecate stuff we have to point teams to use a separate entrypoint for a component. From the consumer side, I think simplifying things into "stable" and "unstable" could help to indicate the stability of an item and our commitment to maintaining its API between minor and patch versions.

Agreed!

I kept that part out of this ADR because it deserves a discussion of it's own. Spoiler: experimental components should not be coupled with stable components in the same package.

[justinbyo]

I'm giving this a 👍

To summarize: I think it solves a very confusing product problem for end consumers.

A couple things to keep our eye on that came up, outside the scope of this ADR:

First, now that "experimental" is a class of Primer components, we can confidently move away from calling non-Primer components experimental. Currently only two non-Primer components live in the experimental-react-component repo, which will most likely be deprecated in favor of the using UI monorepo for shared components. In other words, the switching cost of making "experimental" a Primer-only term is low and realistically I don't think people will be confused in practice.

Second, per @joshblack's comment – how we want to handle bundling in the future to:

• Reduce the number of total entrypoints
• Provide an easier way to deprecate components, or features of a component
• Provide an easier migration process when moving between versions of a component

Third, this issue to update the docs to better reflect the changes in this ADR:

• https://github.com/github/primer/issues/1799

[justinbyo]

👍 See this comment for a summary of my approval and a few considerations we need to make moving forward:

• ADR 010: Merge drafts status into experimental #2856 (comment)

[broccolinisoup]

we can confidently move away from calling non-Primer components experimental. Currently only two non-Primer components live in the experimental-react-component repo, which will most likely be deprecated in favor of the using UI monorepo for shared components.

Does that mean experimental-react-components repo is not going to be maintained anymore?

[justinbyo]

we can confidently move away from calling non-Primer components experimental. Currently only two non-Primer components live in the experimental-react-component repo, which will most likely be deprecated in favor of the using UI monorepo for shared components.

Does that mean experimental-react-components repo is not going to be maintained anymore?

There's an ADR out to make the UI monorepo the place to share non-Primer components. Once it's adopted (which is likely), we'll have to decide what to do with the experimental-react-components repo and we'll most likely migrate its contents to the UI monorepo. However, that decision hasn't been made yet.

• https://github.com/github/platform-ux/pull/1225

[broccolinisoup]

@siddharthkp ADR seems to be approved by the decision maker @justinbyo - Should we merge it?

[erinnachen]

@justinbyo @broccolinisoup This issue: https://github.com/github/platform-ux/issues/1227 tracks the plans for the experimental-react-components repository. I haven't moved it forward because it didn't seem urgent, but I can bump this work up in priority if there's something that needs an immediate response.