docs: add contributor docs #5816
Conversation
|
📚 Branch Preview🔍 Visual Regression Test ResultsWhen a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:
Deployed to Azure Blob Storage: If the changes are expected, update the |
Tachometer resultsCurrently, no packages are changed by this PR... |
caseyisonit
added
the
2nd gen
graynorton
changed the title
rise-erpelding
left a comment
rise-erpelding
left a comment
There was a problem hiding this comment.
This is a really fantastic start! There's a lot of information to be organized, and this does a really good job of laying it all out. I left some comments for things we might consider at some point, but no objections regarding merging this into barebones!
There was a problem hiding this comment.
This is fantastic, and I love the idea of being able to use both AI and a script to keep TOC and breadcrumbs in order!
There was a problem hiding this comment.
I do really like the idea of a table, but will note that I think it'll be really easy to forget to update this. I know part of the migration work we've been doing in barebones included adding the migrated tag in Storybook (for example in Badge) to mirror how we did Spectrum 2 migrations in spectrum-css. It might be nice to find a way to integrate the use of that tag at some point... maybe to have a script or something that looks through the stories files to see what's been migrated. Not necessary now, but a thought for future iteration!
There was a problem hiding this comment.
love this idea! we should definitely chat about this in a team meeting! or here ;) but i want to make sure this isnt lost!
There was a problem hiding this comment.
Yeah, I think there are various things we might do to stay on top of status.
I'm not against the idea of using Storybook tags for this, but one sort of funny thing is that—unlike the situation for the S1 => S2 migration in the CSS repo, if I understand correctly—we aren't starting from a bunch of unmigrated components in 2nd-gen. That is, by the time a component shows up in 2nd-gen Storybook, it will in essence be migrated by definition.
(That was a bit different for the Barebones components, because Ruben "pre-populated" 2nd-gen with stuff copy-pasted from 1st-gen, just so he had something to test the tooling against.)
One thing I've thought about is having some AI-assisted pre-commit instructions...whether they'd be tied to actual precommit hooks I have not yet thought through, but we I think it would be pretty simple to set up Cursor to help us remember to update the status table when we're doing migration PRs. I think Cursor would also be pretty good at doing one-off checks of the table against what it sees in the repo.
In any case, we can discuss what we'd like to do, and then make it so!
| Inside the CSS directory, you can expect to find the following files: | ||
|
|
||
| - `index.css` - This is the source of truth for the component Styles | ||
| - `dist/index.css` - This is the processed version of the component styles; for now, this is the best place to source styles for SWC. When copying files from Spectrum CSS into the 2nd-generation component, using this file will ensure you get the benefits of the CSS build tooling. |
There was a problem hiding this comment.
This might be obvious, but we don't commit dist/index.css so you have to install & build locally to access this file.
There was a problem hiding this comment.
great callout, we should add that context to the intro line
There was a problem hiding this comment.
Yeah, I think we may end up making a bunch of refinement edits to this doc as we flesh out its peers, and this is definitely a good thing to add!
| - Create additional stories showcasing variants, sizes, states | ||
| - Add `tags: ['!dev']` to all non-default stories | ||
| - In HELPER FUNCTIONS section (if needed): | ||
| - Add any utility functions or template helpers |
There was a problem hiding this comment.
I think I see that some of the utility functions here are a little repetitive... for instance, Status light and Badge both use a CONTAINER function. Status light implements a sizeMap function that maybe could be used in some of the other components in barebones, but definitely could be used in other components outside of barebones as we go along.
I believe that the repetitiveness rather than creating utility functions in a place where they'd be reusable is a deliberate choice for now, right? Could be worth mentioning that here or somewhere if we continue with this for more component migrations--to me, one challenge with this work was trying to figure out what's in scope and what's not.
There was a problem hiding this comment.
Yes! And I agree with your point about “scope” — it’s a bit blurry since we defined barebones as "the minimum possible to validate certain requirements" (as outlined in the RFC), but of course, that can materialize differently once you get into the implementation.
In this case we purposely left the utilities in line but we'll want to evaluate which ones we definitely want and find a shared place for those.
The idea is that right after barebones, we’ll look at this first set of components and take specific actions to address this and other questions or open threads that came up during this initial phase 😀
| - Badge | ||
| - Progress Circle |
There was a problem hiding this comment.
thats how i was interpreting that section
There was a problem hiding this comment.
Yeah, those showed up there because I locally had empty folders for Badge and Progress Circle. When the script for auto-generating nav saw those, it created those TOC entries.
Here's what I quickly splatted into a Slack chat—so, subject to refinement, but generally how I see stuff from #5770 getting integrated:
Component analysis should be added as a step (probably the first step, order-wise) in the 2nd-gen Component Migration workstream docs. This would mean making a new folder under
CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-stepand moving theREADMEandcursor_promptfrom docs: 2nd gen component analysis #5770 inside it, making any necessary adaptations in the processThe analysis for each component should move to an appropriate location beneath
CONTRIBUTOR-DOCS/05_component-info. Because I envision the Component Info section evolving to include additional analysis (e.g., analysis of current usage data and patterns), I think the structure that makes most sense might be to add a folder per component, and within each folder include an both an initially empty index file (README.md) and a file containing the analysis from docs: 2nd gen component analysis #5770. My suggestion would be to name that file something likedesign-and-api-analysis.md, and to update the H1 heading in the file accordingly.
| - Import `StoryObj as Story` for consistency | ||
| - Set up Storybook helpers with `getStorybookHelpers()` | ||
| - Configure argTypes for component-specific controls | ||
| - Define and export the meta object |
There was a problem hiding this comment.
Is it worthwhile to mention that we should be adding tags: ['migrated'],? Do we want to keep doing that?
There was a problem hiding this comment.
Good call - probably doesn’t hurt to keep the “migrated” tags for now. That said, “tags” in general probably deserve their own little thought to make sure we’re leveraging them to their full potential (e.g., I can imagine us having "preview", "stable",...)
|
Thanks for the reviews! Going ahead and merging, and we'll refine from here... |
| - [Contributor Guides](02_contributor-guides/README.md) | ||
| - [Adobe Code of Conduct](02_contributor-guides/01_code-of-conduct.md) | ||
| - [Authoring contributor docs](02_contributor-guides/authoring-contributor-docs/README.md) | ||
| - [Style Guide](03_style-guide/README.md) |
There was a problem hiding this comment.
- Should we move this to the contributors section? I can't think of a non-contributor use case.
- I have a JIRA ticket (SWC-996) with a series of accessibility guides, some aimed at contributors, some at consumer, and some at both. Where should it go in this hierarchy?
There was a problem hiding this comment.
Should we move this to the contributors section? I can't think of a non-contributor use case.
Very much open to discussing changes to the shape of the outline. In the specific case of Style Guide, I was thinking of it almost like a Style Reference (hmmm, maybe that's a better name for it) with fairly terse descriptions of style and organization conventions that could be followed by either humans or AIs for various purposes.
In contrast, I was thinking of the stuff in Contributor Guides as being a bit more conceptual and topical, more clearly designed for human consumption.
But all of this is up for discussion and revision!
I have a JIRA ticket (SWC-996) with a series of accessibility guides, some aimed at contributors, some at consumer, and some at both. Where should it go in this hierarchy?
We can discuss this, too, but I think it might show up in this hierarchy in a few ways:
- The description of the work would go in the Workstream Info section somewhere.
- The contributor-facing docs produced as part of this work would go, most likely, somewhere under Contributor Guides
- The purely customer-facing docs produced as part of this work would presumably go not in this hierarchy but in Storybook
- To the extent that there are docs produced as part of this work that are applicable to both audiences, we'd either a) copy-paste the content so it appears in both our contributor-facing and customer-facing docs; or b) include the content in one or the other set of docs and link from the other; or c) come up with a way to share certain Markdown source files so that the same content appears in both docs
Description
This PR introduces a comprehensive contributor documentation system to help maintainers and contributors understand the SWC project's objectives, strategy, and workflows.
What's included
This PR adds a
CONTRIBUTOR-DOCSfolder at the repository root. These docs are just ordinary Markdown files organized within a folder structure that is used to auto-generate breadcrumbs and tables of contents for navigating the docs.The docs are organized into five main sections:
Objectives and Strategy - Explains the strategic context for the 1st-gen-to-2nd-gen transition, including our goals for unifying Spectrum CSS & SWC, building a clean foundation, enabling Spectrum 2 adoption, improving accessibility, and continually improving components. Also describes our strategy for managing disruptive vs. non-disruptive changes through side-by-side development. The current content represents where the project is today, but this section is intended to be evergreen, updated as our objectives and strategy evolve over time.
Contributor Guides - Includes guides for working on the project, starting with the Adobe Code of Conduct and a detailed guide for authoring and maintaining these contributor docs themselves (including automated TOC/breadcrumb generation via a Node.js script).
After this PR lands, we'll gradually migrate basic information for maintainers and contributors that currently exists in various places beneath the
first-genworkspace into this section, updating and cleaning it up as we go.Style Guide - Placeholder for comprehensive style guide covering project-wide conventions and area-specific rules (to be populated in future work).
Workstream Info and Component Info - These two sections establish a dual-view organizational structure for tracking and planning our work, but are mostly incomplete from a content perspective:
Workstream Info provides a workstream-centric view of cross-cutting work. Currently includes framework documentation for 2nd-gen definition/development, 2nd-gen component migration (with a detailed 6-phase migration process), accessibility improvements, component improvements, and 1st-gen Spectrum 2 enhancements. This structure will be populated with detailed planning and status information over time.
Component Info offers a component-centric view for tracking individual component roadmaps and status across multiple workstreams. This folder is intended to contain a subfolder for each component, containing analysis and planning docs specific to that component. Note that PR docs: 2nd gen component analysis #5770 contains component analysis work (relevant to the S1 => S2, CSS => SWC migration) that will be merged into this section after this PR lands.
Together, these sections provide the scaffolding we need to organize our planning and tracking efforts as the project evolves.
Motivation and context
These docs serve several purposes:
Related issue(s)
SWC-1234