docs: improve and clean up contributor docs for barebones merge

[graynorton]

Description

To clarify: the contributor docs are very much a work in progress, and what's in this PR doesn't represent the intended final state. While we hope to make some further incremental improvements before merging to main, we have already done more than was specified in the Barebones requirements, and expect to continue improving the docs well after the initial merge to main.

This PR restructures the contributor documentation to prioritize day-to-day contributor needs and migrates essential guides from 1st-gen documentation, adapting them to reflect the current project structure.

What changed

New contributor guides (migrated and adapted from 1st-gen docs)

• Getting involved
• Using the issue tracker
• Working in the SWC repo (with detailed repository structure explanation)
• Making a pull request
• Participating in PR reviews
• Releasing SWC
• Patching dependencies

Improved documentation structure

• Reorganized sections to prioritize actionable contributor information:
  • Contributor guides - Day-to-day guidance for contributors (WIP)
  • Style guide - Coding standards and conventions (placeholder)
  • Project planning - Strategic planning, workstreams, components, and milestones (WIP)
• Consolidated "Workstream Info" and "Component Info" into "Project planning" for clearer organization
• Moved "Objectives and Strategy" under "Project planning" where it fits more naturally

Root-level improvements

• Created CONTRIBUTING.md and streamlined README.md to provide quick-start information with links to detailed guides
• Added link verification tool to prevent broken documentation links

What's next

This migration is ongoing. Future PRs will continue moving and adapting content from 1st-gen documentation to ensure all contributor-facing information is accessible at the repository root.

Motivation and context

This reorganization makes it easier for contributors to:

• Find practical guidance when they need it
• Understand the repository structure and development workflow
• Navigate from quick-start info to detailed documentation
• Distinguish between tactical contributor guides and strategic planning docs

[changeset-bot]

⚠️ No Changeset found

Latest commit: d1aafa6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview

• Documentation Site
• Storybook

🔍 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-5840

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

[github-actions]

Tachometer results

Currently, no packages are changed by this PR...

[rise-erpelding]

Some of the removed content here doesn't seem to be in the repo anywhere else anymore, is that intentional? I can see how some things maybe could be removed, but there are other sections (Stackblitz, Requirements, Storybook, Linting) that still seem at least somewhat relevant.

[graynorton]

Good catch! The content in the original root README.md wasn't supposed to be deleted; it was just supposed to be moved to 1st-gen, and then incrementally migrated from there. I am quite sure I actually did move it, not delete it, but I suspect that it accidentally got lost when I later rebased on an updated barebones. I'll restore it!

Then, as noted in the PR description, the migration and adaptation of content is a WIP; there will be more PRs to follow this one. Technically, what we've done so far is quite a bit beyond the requirements we established for the Barebones milestone, so finishing the migration of the remaining content isn't a blocker for merging to main—but I am nonetheless trying to get more of it migrated in that timeframe, just on principle.

[graynorton]

FWIW, I just added a note to the top of this PR description to clarify the scope of this PR within the larger arc of contributor-doc improvements.

[najikahalsema]

Some minor changes. I have a larger concern about making sure these documents stay up-to-date and accessible, especially those related to workstreams and status. We definitely need a plan or checklist to deal with updating those frequently. Curious about others' thoughts there.

[najikahalsema]

I kind of don't want to have this live in a markdown file--I'd rather link to our github labels directly just because it's a lot of overhead to maintain.

[graynorton]

Some minor changes. I have a larger concern about making sure these documents stay up-to-date and accessible, especially those related to workstreams and status. We definitely need a plan or checklist to deal with updating those frequently. Curious about others' thoughts there.

@najikahalsema I hear you, but the theory here is that these documents are the place where we establish our plans, not just a place where we document them for others—so as long as we actually get out in front of planning, we shouldn't run into an issue with staleness here.

[najikahalsema]

Looks good! I just had one minor formatting thing I noticed that shouldn't require re-review from me.