ADR 008: Lowering the barrier to entry for experimental components

[siddharthkp]

See rendered markdown

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 2b0e947e1fc4d4b1ceced0ee35730e5006bee323

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[bot]]

size-limit report 📦

Path	Size
dist/browser.esm.js	76.25 KB (0%)
dist/browser.umd.js	76.86 KB (0%)

[lesliecdubs]

Thanks for getting this written up, @siddharthkp!

In order to help move a decision forward, I'm assigning the following:

ADR decision maker: @mperrotti Decision deadline: EOD Wednesday, 31 August

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)

[siddharthkp]

While we accept ownership of these new components, we do want them to adhere to conventions that we are strictly following in our team. In case of urgent upstreaming, we will need to come up with some compromise. And I believe this is a good one. > Contributors will still have the opportunity to contribute directly to primer-react, provided they follow our guidelines and component sizes are minimal. In the specific case of this ADR ie a markdown editor component, I would want our design team/ally teams to be involved in it. It could also happen that we can breakdown this large component into smaller parts and have them in primer-react. Either way, a buffer for incoming components with shared ownership between product teams and primer-react is a great idea IMO

@pksjce Thank you for this articulation! This is really helpful, I'm going to start quoting that 😄

[mperrotti]

@siddharthkp is going to make some updates and get feedback from other teams with similar challenges.

Monday Aug 15 is going to be too soon to freeze this decision cc @lesliecdubs

[siddharthkp]

Update!

After collecting feedback from the team, I have updated decision no.3, the location where the source code of experimental components would live from new repository github.com/primer/react-candidates to existing module github/github/.../modules/react-shared

### Decision
- 3. code repository: To support different conventions and processes for experimental components and convey shared ownership between primer and product teams, we should keep them in a new repository `github.com/primer/react-candidates`
+ 3. The code for experimental components should live in [github/github/modules/react-shared](https://github.com/github/github/tree/master/app/assets/modules/react-shared) and published as individual packages as suggested in point 2.
+
+  The monolith already has a place where reusable react components live. This has the lowest barrier to entry for folks working in the monolith.
+
+  Acknowledged risk: It would introduce some additional work for non-monolith projects when upstreaming reusable components. We should work on improving the development and publishing workflow for react-shared.

The rendered markdown shows the latest version.

[colebemis]

Some notes from my conversation with @dgrief about publishing the react-shared directory as a package the memex can consumer:

• Overall, Dusty thinks publishing react-shared seems like reasonable solution to our current problems and prefers that approach to the alternatives (i.e., creating a new repo)
• We could/should publish the package to the GitHub Package registry (instead of npm). It would be easier to keep the package private and we already have the infrastructure set up for it in dotcom (i think)
• Ownership in dotcom is already handled via CODEOWNERS so we wouldn’t have to set that up ourselves
• Memex bundles all their dependencies so we run the risk of bundling react-shared components twice in both memex and dotcom. However, this is an existing issue. react, react-dom, and @primer/react are already being duplicated between memex and dotcom so this doesn’t seem like a blocker

— Slack thread

[lesliecdubs]

Thanks for the great discussion around this proposal!

@mperrotti I'll push out the decision deadline to Wednesday 24 August, although please feel free to complete the decision-maker duties prior to that date if you're able. Please ping me again if more time is needed.

[howdyray]

@siddharthkp - Thanks for writing up with ADR, love the idea of creating a pressure release valve for teams. Have we discussed how might we support this on the design side yet? I'd love for us to have a similar structure so designers can start at the same place (e.g. Figma) and have awareness that these shared components are available in code before designing another iteration of them.

[siddharthkp]

@howdyray Not yet. The follow up work after this ADR gets approved would be on docs and discoverability of these components, which should help us spot emerging patterns and candidates for system components