spectrum-web-components icon indicating copy to clipboard operation
spectrum-web-components copied to clipboard

Published 20 hours ago • verified publisher icon adobe

Targeting 1.0!

Open Westbrook opened this issue 4 years ago • 6 comments

This is a discussion issue to figure out what we'd need to do to feel ready for a 1.0 release of the various packages. We had previously outlined a list of issues that would allow us to get there, what seems like a lifetime ago, and it still has one "Stretch Goal" issue that we've been slowly making advances on: https://github.com/adobe/spectrum-web-components/labels/1.0.0

Things that I can think of just now to take into account for a possible 1.0:

  • shadow DOM encapsulates our implementation, so as long as we maintain the API surface we can make a good number of changes post-1.0 that wouldn't be considered as breaking
  • we've recently caught up to the most recent Spectrum CSS
  • pre-1.0 releases are counted as "breaking" at the "feature" entry of semver which can cause trouble when trying to depend on "mixed" releases of the various packages we vend, sometimes we've accounted for that and made "features" fix: ... but sometimes a feature is a big feature and while it doesn't "break" anything it needs a "feature" version, e.g. content direction...
  • we chose not to rely of matched version releases, so we could go 1.0 with some, but not all packages. Secondary issues are likely to arise from that, but possible by design
  • packages that support non-encapsulated functionality, e.g. overlay would then have a more strict update pattern in contexts similar to #848 and #764 that beg for possibly serious implementation changes, if not specifically API breaking changes 🤞

I'm sure there's much more context that I missing, but I wanted to get this conversation into the space so we could find as many realities to keep in mind as we formalize the path from here to there together.

Westbrook avatar Sep 02 '20 17:09 Westbrook

We're using components in production on https://lightroom.adobe.com and from my point of view "we're ready!" from the perspective of components being of good quality and usable.

On the process/support front though, I think there's probably a bit of work. Once we're 1.0 I think it'd be good to support patch releases for 1.x components if we later to a 2.x release.

adixon-adobe avatar Sep 02 '20 18:09 adixon-adobe

This issue also has a possibility of some breaking changes, particularly to the sp-textfield component: https://github.com/adobe/spectrum-web-components/issues/475 I've a "working" branch of the field-label as a standalone Spectrum CSS delivery in westbrook/label, but it doesn't actually attach to anything yet. Research here may lead to proposing a desire to move form elements into light DOM, but more research is needed before there is anything solid there.

Westbrook avatar Sep 08 '20 04:09 Westbrook

Also important to think about here: https://github.com/adobe/spectrum-web-components/issues?q=is%3Aissue+is%3Aopen+label%3Aa11y I'll try and make some time this week to tag these with a form of breaking|possibly breaking|fix change labels so we have a better understand of how that work interacts with this conversation.

Westbrook avatar Sep 14 '20 00:09 Westbrook

The recent Spectrum CSS releases finally get around to renaming packages as per the most current Spectrum specification (e.g. BarLoader => ProgressBar or Dropdown => Picker) and in theory represents a serious breaking change to our component offerings. This could be mitigated by offering both old and new API surface as extensions of each other, but it's hard for me to see whether that's helpful (eases migration) or hurtful (delays migration) in the overall healthy relationship between the library and its users.

There is work in progress to catch up to some of those changes in this diff: https://github.com/adobe/spectrum-web-components/compare/westbrook/spectrum-css?expand=1 so people can see the delta there.

Westbrook avatar Sep 24 '20 14:09 Westbrook

Trying to track issues that need to be cleared before a 1.0 here: https://github.com/adobe/spectrum-web-components/projects/1

It's possible that some could be dropped at "feature releases" post 1.0, so speak up where you think we shouldn't be blocked.

If there are things missing (please create issues) or things not included that area already listed in the issues, feel free to let me know here to get this project listing closer to complete.

Westbrook avatar Nov 22 '20 19:11 Westbrook

@joekukish makes the great point that pre-1.0 we should normalize non-t-shirt sized uses of the small attribute, or size="small" as a long string to prevent unneeded API breaks.

  • sp-card
  • sp-progress-circle
  • sp-dialog
  • sp-dialog-wrapper

Westbrook avatar Aug 03 '21 13:08 Westbrook