Skip to content

RSP V3 Reconciliation Plan

Jump to bottom
Larry Davis edited this page Mar 6, 2020 · 7 revisions

Preface

In order to support RSP V3 effectively, the highest priority should be getting Spectrum CSS back in sync with their fork. This will allow them to absorb changes to Spectrum CSS without merge conflicts or import scripts, and enable us to do the required feature development from a common starting place.

Plan

In order to do this, we must do the following, in this order:

1. RTL Support.

Since RSP V3 is supporting RTL, every component needs to be touched to have RTL support in Spectrum CSS.

RTL touches every border, padding, margin, width, and height in every component, and if we don't have it in Spectrum CSS, then every single update to any of those properties causes a merge conflict with RSP V3's fork.

This PR implements RTL support and needs to be finished/reviewed by the team: https://github.com/adobe/spectrum-css/pull/532

2. Reconcile changed components in RSP V3's fork

There are a number of components that have had changes in RSP V3's fork that we need PRs for so the changes can be reviewed by the Spectrum CSS team.

  • breadcrumb - layout switched to block, has .is-reversed state
  • button - Tool removed, manual RTL support for hold, Action Button Emphasized implemented, mobile :active changes, ButtonGroup and ButtonGroup Connected implemented
  • buttongroup - Tool removed, focus outline fixed
  • dialog - CSS grid, changes to warning/error
  • fieldgroup - --positionSide added, horizontal added, SUIT issues
  • fieldlabel - changed to flex layout, added --positionSide, form changed
  • link - added quiet link, added secondary link, changed underline and cursor
  • menu - focus fix, selected color changed
  • stepper - line height, focus changes
  • tags - Icon/Avatar markup changes, clearbutton renamed, deletable -> removable
  • treeview - added Treeview Heading

In progress:

  • inputgroup - added is-disabled, datepicker endField and friends, focus-ring tweaks
  • search - DNA var changes, markup changes
  • textfield - markup changes, SUIT issues

These components and their priorities are documented here: https://github.com/adobe/spectrum-css/wiki/V3-Changes-and-React-Sync

Each of these components needs a PR to be sent by the Spectrum CSS team to the Spectrum CSS project, using the code from RSP V3's fork. The following steps outline how that is done

  1. Create a Spectrum CSS branch off of rtl, copy in the component's CSS from RSP V3
  2. Commit the changes
  3. Change the author of the commit to whoever authored the changes (git commit --amend --author="Rob Snow <rsnow@adobe.com>")
  4. If applicable, update all examples in .yml files to use the modified markup (the RSP V3 fork does not have .yml files with updated examples)
  5. If applicable, add examples for any new modifiers/states included in the CSS
  6. If applicable, add a migration guide for the breaking changes (similar table as we did for Typography http://spectrum-css-archives.s3-website.us-east-2.amazonaws.com/2.17.0/docs/typography.html#migratingfromdeprecatedtypography)
  7. Send a PR against the rtl branch
  8. Start reviewing it and ping the relevant authors is necessary.
  • evaluate browser support (i.e. new Dialog uses grids)
  • ensure design is correct or at least as broken as it was before (paste over XD files)
  • ensure any CSS changes conform to SUIT
  • ensure any CSS changes conform to existing naming conventions

3. Perform normal release with focus ring support

The "halo" focus ring change needs to go into V2, so before we make a breaking change with RTL support, we'll release focus ring.

4. Perform beta releases with RTL support

Once the RTL PR is in, we should release beta major versions for all of the components. RSP V3 can then be updated to use those beta versions and delete the 40+ unnecessary components from its fork, leaving only those that still need a PR.

5. Perform beta releases with RSP V3 changes

Once RTL betas have been released, we can start merging and releasing betas for RSP V3 changes listed here https://github.com/adobe/spectrum-css/wiki/V3-Changes-and-React-Sync

6. Perform remaining breaking changes

Any additional breaking changes should be made AFTER the beta versions are released, that way RSP V3 does not have to absorb breaking changes when moving to use the Spectrum CSS published packages.

Breaking changes are listed here: https://github.com/adobe/spectrum-css/labels/breaking%20change

A rough schedule for those changes is here: https://github.com/adobe/spectrum-css/projects/11

7. Release Spectrum CSS 3.0.0 bundle

Once those breaking changes are done, documented with migration guides, etc, we can perform the Spectrum CSS 3.0.0 release and the individually versioned components, with full RTL support and all the planned breaking changes

Rationale

Following the outline above will put us in a good position to support React Spectrum V3, and will have releases out that, after a small modification to their build process, can be included in their repository to avoid the need for a fork for at least 40 of the components.

Timeline

if we can get beta releases out with RTL support by 3/6, we can proceed with the rest of the breaking changes the sprint after that, and drop 3.0.0 perhaps the sprint after that. (edited)

Clone this wiki locally