[Kibana upgrade strategy] Revisiting longstanding processes and design decisions

[chandlerprall]

Inspired by a comment in an upgrade (elastic/kibana#144845 (comment)).

The EUI team performs Kibana's upgrades, which means we run into cases where we need to support code/designs that no longer match our recommendations or design direction. How do we want to handle these?

Historically, when we've known about or anticipated conflicts from breaking changes we provide the upgrade path in the PR. This is almost always how to apply the update in a way that doesn't change its look or behaviour. The instance above is no different, but revisiting this approach is worthwhile to ensure we're still on the same page from 4+ years ago.

[ryankeairns]

Thanks for adding this example.

If more of these types of questions - regarding longstanding processes or design decisions - crop up, then let's capture them here, convert to a new issue (if needed) and assign somebody who can take a fresh look. We can prioritize these into our sprints, as needed.

[mdefazio]

Great discussion to bring up. TY.

I can absolutely understand the difficulty in having whoever is running the EUI upgrade to go through and fix and the small bugs/breaking changes. (Which i'm assuming happens now?)

There's several of us on kibana-design as a reviewer—but only required that one of us give the approval. This works, but if we find an issue, are these blockers? Do we know who to bring it up to? Perhaps there is also a rotating point person from platform design to work with EUI and the other designers to get these small fixes through? (Granted, this would need to be built into our schedules/work load).

Might help us acquaint ourselves more with the new EUI features / fixes and maybe align our designs more?

[elizabetdev]

Historically, when we've known about or anticipated conflicts from breaking changes we provide the upgrade path in the PR. This is almost always how to apply the update in a way that doesn't change its look or behaviour.

This sounds good to me. IMO the upgrade PR should only apply the update in a way that doesn't change its look or behavior. But I think we should come up with a better approach to handle scenarios where we have new designs or new components.

And I can give an example of a design update/recommedantiosn that went well and one that didn't go well.

A design example in that we recommended a change and the process went well

As part of the work on the EuiCommentList enhancements, we decided to create a EuiTimeline component. Because one team was overriding the styles of the EuiCommentList to create a very custom timeline.

So we decided to talk with the team and let them know a new component was coming to their use case and Yulia created an issue to track our work.

When we opened the PR to upgrade EUI in Kibana I let Yulia know that once that PR was merged she could start her work.

The implementation of the EuiTimeline worked well. 👍🏽

An example that didn't go well

Now I can give another example. The EuiCommentList new design recommendations were never implemented in Kibana or other projects like the Dream Machine.

One thing that we noticed is that a lot of teams needed to override the styles of the comment list to add a markdown editor for example. So we improved the component to allow custom components to be passed.

When Constance opened the PR to merge EUI in Kibana she changed multiple codes to remove the overrides. She fixed conflicts from breaking changes and that's it. Our job is done.

But we also add some new features and some new design decisions that were never well implemented. Because it required more dedicated work. As Yulia did.

One of the main changes in the comment list was:

The avatar icon placement no longer flip-flops with the update icons. Update icons appear before usernames on the left side of the timeline.

But I still see a lot of teams with these icons flip-flopping, which we don't recommend. So should it be us to fix this in the upgrade PR?

Well... It doesn't sound right to me.

Solution

As @mdefazio pointed out:

Perhaps there is also a rotating point person from platform design to work with EUI and the other designers to get these small fixes through?

I think this would work for small fixes. But for major fixes, I would prefer an approach like the one I exemplified with the EuiTimeline.

In our Kibana upgrade, we should only make sure the new version is merged and no conflicts are happening.

But if we have a new design coming. Like the comment list example, or timeline example:

• We can open an issue after the upgrade PR is merged with the path/how to implement the recommended design and we should tag teams
• Teams should then prioritize their work (maybe they can open their own issues tracking ours)
• In some cases, we or platform designers can help or even implement
• Should this issue live in Kibana? What about the other teams?