Workflow and contribution guidelines feedback

[kurtdoherty]

@willmcvay Here's my comments/questions regarding the workflows and contribution guidelines for Elements. Apologies for the wall of text 😬 As I've mentioned previously, it would be great if we can eventually have this kind of document review happen via a more collaborative, close-to-the-source tool, but hopefully Discussions will suffice for now.

General

• praise: Thanks for putting all of this content together. It’s great to have something concrete to read, think about, and discuss.
• note: A lot of the Console Cloud FE team members use Conventional Comments when reviewing documents/PRs etc. It’s what I’ve used here and is generally pretty self-explanatory, but take a look at it if you need clarity on what the difference between “issue”, “suggestion”, “note” etc are.

High-level workflow

• suggestion: Seems like bug reports would typically go via an Engineering Review first, and would only be taken to PO/Design if Engineering needed clarity on what the behaviour should be or the fix required some kind of change to the Design System itself.
• suggestion: Would be valuable to track how much time/effort each of these stages takes as this will give us insights into whether any particular stage becomes a bottleneck.
• suggestion: We should strictly avoid contributing components/features to Elements that have no use in the Design System itself. That is, if we receive external feature requests, they should be considered as feature requests to the Design System itself, not just to Elements.
• question: Does Elements receive many external feature requests currently? If not, is this something we really need to be concerned about at all?
• question: Who is responsible for communicating new “Product Feature Requirements”?
• question: Do we really need the complexity of two separate release channels? Can we simplify and just say all new work, breaking or not, happens on v5 and we only facilitate bug fixes for v4 (e.g. it’s entered “LTS”)?

Developer workflow

• todo: Fix typo Environments section; second “Dev Beta” should be “Prod Beta”.
• question: Do we really need the complexity of two separate release channels? Can we simplify and just say all new work, breaking or not, happens on v5 and we only facilitate bug fixes for v4 (e.g. it’s entered “LTS”)?
• question: Will all Reapit/internal contributors have merge permission, or are we going to lock it down to a group of “owners”.

Developer contribution guide

• issue: Can the React 18 requirement for Elements be relaxed to React 17? Are any React 18 APIs being explicitly used? Console Cloud isn't on React 18 yet and I believe there’s a few old dependencies in our current tech stack that aren’t React 18 compatible and have a considerable amount of work required to upgrade (MUI v4 is one that comes to mind).
• suggestion: Would be good to clearly communicate that internal product consumers are the primary focus of Elements (at least for v5 initially), not third-party integrators. Since our internal products will (mostly) trend towards React-first usage, I think it should be acceptable for CSS-only usage in v5 to be quite pragmatic.
• suggestion: Would be good to have strong conventions around prop and CSS variable naming and those conventions should be followed by both the Design System components in Figma and what is implemented in Elements.
• suggestion: There are more component design patterns available to us than callback/render props. Some of these patterns provide more/less flexibility than others, often in exchange for more/less “boilerplate”. We ought to discuss what level of flexibility we actually need in Elements and use that to guide the interface design of new components.
• question: The focus on things like minimal JS and native input behaviour seems to put Elements in conflict with the Design System. For example, the Design System will likely require a more advanced date picker than is provided natively by browsers; would this kind of component be implemented in Elements, or would that be left to the consumer?
• question: Describing React components as being “batteries included” is vague. Does that mean they can include behaviour like focus management, component state management, form validation behaviour and so on, or will that still be up to individual product engineering teams to take care of?
• question: Despite Elements being dependency-free in the production sense, it also sounds like existing usage of third-party dependencies will constrain the implementations of components in v5 and beyond. Do we expect these constraints to be maintained long-term and how do we expect to take the same approach with all our products and the dependencies they may use.
• thought: I can see mobile-first requirements becoming a potential barrier to entry for product engineering teams that are working on desktop-only products but need a new component (obviously would depend on the specific component, as some components are trivial to do in a mobile-first manner).

[kurtdoherty]

Oh, and...

Developer contribution guide

• suggestion: I think we could provide some deeper material around testing best practices for Elements. I think this is actually a pretty important topic for us to talk through given Elements will increasingly become a single point of failure for the UI of all our web products. We have some shiny new docs within the Console FE team that I can share if you'd like to see how we do things; at a glance, it looks like there's already pretty good alignment, but having some specific guidance for contributors would be useful.

[alexander-bobin]

Piggy backing on this so we have feedback all in one place. Thanks for writing this up, Will 🙏

High level

It's becoming clear that contributing to Elements will be vastly different to contributing the smaller Console Cloud design system. Of note: the audience, mobile first, CSS only backup, no third party libraries (e.g. MUI). All of that changes the game quite a bit. I am keen to see how we plan to contribute to and use Elements while also allowing for the rapid change required within Console Cloud (e.g. Angular to React migration, upcoming large features).

This more of a question for Kurt.

Details

• Form styling is one thing but behaviour is another. Kurt has mentioned this. Gut tells me we can't provide meaningful form components without getting into the depths of behaviour. Maybe we can dig deeper into this to learn more.
• "always keep in mind offering an "MVP" experience for non-React devs". Also mentioned by Kurt. Would like to know more about where we strike the balance there. Also to see some of that MVP experience in use.
• Keen to see some examples of how the team has already handled mobile first. Just hear a couple of stories. How did things pan out. Think it's going to be easy in some cases and a real challenge in others.
• "All of out component and class names" typo. Think it should be "All of our component and class names"

[alexander-bobin]

Final thought on process... when building the Console Cloud design system we found that, on one or two occasions, designs were not 100% complete until we came to planning implementation and found some gaps. The remedy was open discussions with the design team and some revisions. Even though it is an edge case, it would be good to show this is possible in the flow diagram.

[willmcvay]

I agree with what you are saying but reckon that's something we can all deal with sensible pragmatic conversations with colleagues - was intended to be a high level process, not something rigid or written in tablets of stone. We're all at the end of a DM for a chat right 😄

[willmcvay]

• note: A lot of the Console Cloud FE team members use Conventional Comments when reviewing documents/PRs etc. It’s what I’ve used here and is generally pretty self-explanatory, but take a look at it if you need clarity on what the difference between “issue”, “suggestion”, “note” etc are.

Yep, sounds sensible, feel free to add to the Wiki

[willmcvay]

• suggestion: Seems like bug reports would typically go via an Engineering Review first, and would only be taken to PO/Design if Engineering needed clarity on what the behaviour should be or the fix required some kind of change to the Design System itself.

Pragmatic approach obviously, but generally I would expect bugs to be triaged by the PO so they can be prioritised in the platform sprint cycles and / or relevant engineers being targeted to fix.

[willmcvay]

• suggestion: Would be valuable to track how much time/effort each of these stages takes as this will give us insights into whether any particular stage becomes a bottleneck.

Honestly, I would say e2e, if something is a priority for a development team, from raising a ticket to it being in production shouldn't take more than a day, plus the time it takes to write the code. It just requires proactive communication - we are all colleagues at the end of the day!

[willmcvay]

• suggestion: We should strictly avoid contributing components/features to Elements that have no use in the Design System itself. That is, if we receive external feature requests, they should be considered as feature requests to the Design System itself, not just to Elements.

Completely agree - the component library should be driven by the design system and look to implement it as close to 1:1 as possible, albeit there may be some pragmatic exceptions.

[kurtdoherty]

albeit there may be some pragmatic exceptions.

What kind of "pragmatic exceptions" do you have in mind here?

[willmcvay]

If a feature is in the design system but would require adding external dependencies or an excessive amount of dev - a good example would the fancy date picker example below.

[willmcvay]

• question: Does Elements receive many external feature requests currently? If not, is this something we really need to be concerned about at all?

Yes, but not loads and mostly they are "internal external", meaning other teams in the business outside of the design team, eg UK Digital and PayProp. It's not the core workflow, just something to keep in mind.

[willmcvay]

• question: Who is responsible for communicating new “Product Feature Requirements”?

I would say Product and or Design - ideally a design lead process always.

[willmcvay]

• question: Do we really need the complexity of two separate release channels? Can we simplify and just say all new work, breaking or not, happens on v5 and we only facilitate bug fixes for v4 (e.g. it’s entered “LTS”)?

I don't envisage making many feature changes to v4, however, we have a big estate using it and migrations with breaking changes to v5 are something we need to manage. If say the UK digital team need a new component and they aren't ready to migrate, we should absolutely supply it in v4 if we can. LTS still requires proper maintenance, upgrades to libraries and so on as well.

The workflow implemented really only requires one manual step, which is to review and merge a PR post v4 release, back into the beta v5 channel - this shouldn't really be too arduous and certainly preferable to doing the changes in two places.

There will be A LOT of breaking changes in v5 hence managing this way, when we've resolved all our naming conventions, and got a v5 we are happy with, we can probably get rid of the two channel approach, knowing fewer breaking changes in v6 and beyond.

[willmcvay]

• todo: Fix typo Environments section; second “Dev Beta” should be “Prod Beta”.

Good spot, fixed!

[willmcvay]

• question: Will all Reapit/internal contributors have merge permission, or are we going to lock it down to a group of “owners”.

I have no issues giving everyone permission, provided we all mindful of the collective and best efforts to not break things :-)

[kurtdoherty]

I think this will be worth further discussion. It's closely related to testing practices across Elements and any products using it, but there's a distinct risk of changes in Elements causing a visual or functional regression in a product. I think this risk is magnified if individual product engineering teams are able to autonomously push through changes in Elements related to their own product, especially if there's no easy way for them to validate their changes behave appropriately in other products.

[willmcvay]

There is a difference between contributing and releasing the project. There will be robust controls over who can release a version and a solid QA process - there is a ticket on the board #52 for visual regression testing for example.

[willmcvay]

• issue: Can the React 18 requirement for Elements be relaxed to React 17? Are any React 18 APIs being explicitly used?

useId is one I can think of. Not a biggie though, we can easily roll our own useId hook that can be replaced with the native at a later date. TBH, we only dropped 17 support about a year ago so I don't think there are are going to be big compat issues. Can you raise a ticket to investigate and we'll look into it.

[kurtdoherty]

I've raised a ticket 👍

[willmcvay]

Answered on the ticket :-)

[willmcvay]

• suggestion: Would be good to clearly communicate that internal product consumers are the primary focus of Elements (at least for v5 initially), not third-party integrators. Since our internal products will (mostly) trend towards React-first usage, I think it should be acceptable for CSS-only usage in v5 to be quite pragmatic.

I think we're largely there but yes, we can add to the docs in v5.

If you look at how storybook is structured, we typically have a "basic usage" which is the "styles only" laid out in a story and the "React Usage" which is with the added React interactivity. TBH, this is really easy to maintain (we are writing the styles anyway), and don't see why we wouldn't stick to that pattern.

In summary, yeah, we're already pragmatic and that's totally fine.

[willmcvay]

• suggestion: Would be good to have strong conventions around prop and CSS variable naming and those conventions should be followed by both the Design System components in Figma and what is implemented in Elements.

Agreed, I saw Andrei's work on variable naming, as well as the component name conventions in the design system. Happy to take the hit and fully align with Figma on both for v5.

[kurtdoherty]

Further to this, I think it would be good to consider requiring a Designer and Engineer to formally agree on a component's interface and record that decision for others to see. Kind of like FE and BE taking a schema-first development approach and agreeing on the shape of an API's endpoints, if design and engineering can be explicitly agreeing on the interface to our UI components, I think that'll help shift a bunch of good discussion earlier in the process.

[willmcvay]

• suggestion: There are more component design patterns available to us than callback/render props. Some of these patterns provide more/less flexibility than others, often in exchange for more/less “boilerplate”.

Agreed, and happy to discuss always. Experience has taught though, that flexibility reduces issues down the road where people want "foo" behaviour and we don't support, leading to a feature request and more work long term. My sense is most people will have their own wrappers over common behaviours in their applications that make sense to them, for example integrations with their API or preferred form lib and validation tool.

[kurtdoherty]

My sense is most people will have their own wrappers over common behaviours in their applications that make sense to them, for example integrations with their API or preferred form lib and validation tool.

I think there's more to discuss here, specifically on what kinds of Design-System-defined behaviours will be handled by Elements, and which ones won't. It seems like we may not have a clear answer for that yet, at least w.r.t to forms, because some behaviours (like those around forms) may require us to be opinionated about what third-party libs are used.

[willmcvay]

Yes, agreed, we'll need to support a base line set of core libs as a reasonable standard. We already support a React Starter template and that will be developed as part of the wider tech strategy of the business. I can walk you through this stuff offline.

[willmcvay]

• question: The focus on things like minimal JS and native input behaviour seems to put Elements in conflict with the Design System. For example, the Design System will likely require a more advanced date picker than is provided natively by browsers; would this kind of component be implemented in Elements, or would that be left to the consumer?

I think left to the consumer. The overhead of managing releases and maintenance around 3rd party components proved counter productive in the past - you mention your own issues with MUI above for example.

Also, different horses for courses - whilst the native date picker isn't very attractive in Chrome, it is extremely performant, works nicely on iOS and android (you get the native mobile controls), and integrates with any form library out the box, with no modifications.

[willmcvay]

Internally, we have another package in Foundations called @reapit/utils-react where we put reusable React Components bundled with third party libs eg file uploaders, rich text editors and image croppers. Happy to look at tidying up and distributing that as a separate project.

[kurtdoherty]

I like native inputs too (for all the reasons you cite), but the Design System is pretty much guaranteed to want a more customised UI/UX for desktop products. If that kind of thing doesn't belong in Elements, then we'll need somewhere for them to go (maybe @reapit/utils-react is that place 🤷), otherwise our products will solve it themselves and we'll continue to see duplicate effort when changes to those kinds of components occur in the Design System.

[willmcvay]

Yep, a separate lib makes most sense in that case, agreed

[willmcvay]

• question: Describing React components as being “batteries included” is vague. Does that mean they can include behaviour like focus management, component state management, form validation behaviour and so on, or will that still be up to individual product engineering teams to take care of?

Can have as many batteries as we like, provided they are generic. So example: InputGroup handles state management, validation errors and so on however, it is not tied to "Reapit API errors" or "Console Errors" - we need to be able to share the library, so we would deal with our own API error handling and pass that error to the component. Hopefully makes sense.

[kurtdoherty]

Yes, being agnostic of API entities etc is a given. I'm referring specifically to UI behaviours. As I mention in a comment above, I think there's more to discuss around which UI behaviours make it in to Elements and which don't.

[willmcvay]

• question: Despite Elements being dependency-free in the production sense, it also sounds like existing usage of third-party dependencies will constrain the implementations of components in v5 and beyond. Do we expect these constraints to be maintained long-term and how do we expect to take the same approach with all our products and the dependencies they may use.

No, keep it as simple as poss essentially. This is why we feel we made mistakes previously by incorporating third party libs and so on - caused waaaay more problems downstream for upgrading. Since going largely "vanilla" React and CSS, we've had virtually zero compat issues with third party library upgrades like Hook Form and so on. Don't want the tail wagging the dog 😄

[kurtdoherty]

I'm not suggesting React Hook Form should be included in Elements as a dependency. I'm pointing out that the guidelines explicitly mention inputs must be compatible with React Hook Form, which makes the lib behave as an implicit constraint.

To put it another way, while React Hook Form is not an explicit dependency of Elements, it seems to constrain Elements as though it were. While this constraint is simple to work with, would we expect Elements components to maintain compatibility with other dependencies that may be used by a particular Reapit product?

[willmcvay]

We are already tied to a greater or lesser extent TBH - we have big estates both in UK and ANZ that need support. The way of working has always been to dog-food Elements internally and fix any bugs that arise with third party lib compatibility - I don't see that changing, it's just normal dev workflow.

[willmcvay]

• thought: I can see mobile-first requirements becoming a potential barrier to entry for product engineering teams that are working on desktop-only products but need a new component (obviously would depend on the specific component, as some components are trivial to do in a mobile-first manner).

We're asking for best efforts here and perfection not being the enemy of good enough. New components should at least be functional and look decent at all resolutions - their suitability for all resolutions is a separate question for product and design teams to think about.