[RFC] Revamp contributor documentation

[Sidnioulz]

Summary

This RFC proposes to

• rework the contributor doc to smooth out newcomers' experience
• provide more comprehensive guidance on common issues
• give more visibility to contribution docs on the website

Problem Statement

Generally speaking, the contribution doc needs a bit of maintenance effort.

• There are significant differences between CONTRIBUTING.md and the website
• The proposed entry point for newcomers (yarn start) has a few defects and isn't what most of the team think is the easiest entry point
• The doc is missing a few bits here and there on how the repo is set up, and what commands you'll need on the day to day for simple tasks
• More specialised workflows (doc contribution, running E2E tests) aren't entirely documented
• The troubleshooting section is missing a lot of hard-earned knowledge from the team

We're also not entirely sure how much visibility the doc has. In particular:

• Is CONTRIBUTING.md more/less often used than the website?
• How many unique visitors to the contribution doc? How many are repeat visitors (i.e. people who actually refer to the doc while working)?

Non-goals

• We don't want to question how contributions are organised or to make changes to workflows
• We don't want to create new recurring tasks for the team beyond maintaining the markdown written in the docs

Implementation

On doc visibility

• Send a survey on Discord #contributing to understand where contributors seek help
• Check RUM statistics on the contribution docs site
• Decide whether to move contribution docs to the top level of the site alongside Docs, Addons, Showcase, etc.

If we do move it to the top-level, the following sections can be grouped up:

• Existing Contribute section
• Existing Addons section on addon authoring
• Any relevant doc on framework authoring

On docs content

I want to make the following updates.

Landing page

• Rework copy to be more user-activity based than business-domain based (e.g. Propose a feature rather than Write a RFC)

Project setup

• Realign Node version on 22/24 instead of 18
• Give instructions to install fnm on the website
• Recommend WSL for Windows users on the website
• Remove mention of disabling CI in CONTRIBUTING.md once CI: Provide basic CI jobs for forked repositories, and disable our own jobs #32632 is merged
• Remove mentions of setting a double upstream on storybook, or place it in an advanced section
  • it's relatively difficult for Git beginners to handle multiple upstreams
  • GitHub provides a native UI for synchronising forks with next
  • if users regularly create branches and open PRs, we could set a threshold from where we more systematically invite them to the org
  • alternatively, we could explore automations that do the setup for end users when they clone the repo, a bit like the addon-kit's welcome script
• Newcomers sometimes end up with yarn task not installed because they don't do yarn start, thinking they don't need a sandbox; and they instead try to yarn task compile
  • Always make newcomers type yarn in the monorepo root and in code/
  • Clarify how yarn task works and how to install it
  • Clarify why it's the yarn in code/ that actually installs deps (and that it's equivalent to yarn task install
• @jonniebigodes to check if the documentation on yarn task tasks is expired or up to date

First contribution workflow

• Instead of telling users to use yarn start, let's switch to yarn storybook:ui which is easier to run, has better HMR support, and provides more stories covering Storybook internals
• We could consider a yarn task ui command if we want to provide a homogeneous interface to newcomers

Making code changes

• The yarn build command could receive a bit of love
  • passing flags without a package name does nothing, but should skip asking about the flags
  • package names in the inquirer list do not match package names supported by the CLI
  • a full example with package names could be added under the paragraph with addon-docs
• We should tell users what to do when HMR stops working. Sometimes build --watch crashes because of invalid code being saved in the IDE; then it needs to be relaunched, and Storybook too; we kinda explain that but imo not explicitly enough; let's discuss if this needs to go into Troubleshooting or within the section
• CONTRIBUTING.md talks about unlinked mode for sandboxes, I'm not sure if this is still relevant? Should we remove it?

Making changes - adding stories & tests

• Consider using examples of stories that do not involve addon templates for the first readthrough, as these are less obvious
• Mention that addon templates may not have the same native HMR support as normal stories (@tmeasday could you please clarify, from a developer's perspective, how template stories differ from regular stories? is it correct you need to reload SB for them to be picked up?)
• Clarify when to test using what methods, instead of recommending only unit tests
  • UI related -> stories (especially CSF4 .tests?), add E2E if stories aren't possible (difficulty mocking, interactions between components)
  • Core lib stuff -> story if possible + UT always
  • Automigrations -> UT always + testbed repo (always?)

Creating new Recipes pages

On top of the "Code" page we currently have, it'd be nice to have dedicated recipe pages that explain how to

• Contribute to the UI
• Contribute to an addon
• Contribute an automigration
• Contribute an addon
• Fix a framework bug
• Contribute to the docs pages
• Run E2E tests
  • I think we should write one page with one section per type of test, with clear instructions
    • e2e-tests that can run by setting up a sandbox, uncommenting playwright.config, and running in VSCode
    • portal story tests that can also run in VSCode if you run the right portal story env and do the right tweak inside the VSCode extension config
    • stories test run if playwright available on local machine
    • etc.
  • Advanced playwright usage
    • Run in --headed, both via CLI and IDE;
    • keep browser open after test ended, both CLI/IDE
    • playwright show-trace for advanced error debugging (can also download traces from CircleCI job artifacts)
    • recording under cursor, useful to edit/write locators for new tests

Because these all have different commands and workflows, and it's nice to have a summary page (cheat sheet) with all the commands and info you need for your task at hand.

The framework/addon recipes could redirect to relevant docs sections, and the other pages could explain the typical commands, testing standards, etc. For example, automigrations require linking to the built CLI from a third-party repo acting as a testbed. Encouraging this workflow, and encouraging publishing the testbed, will help reviewers down the line.

Switching to Recipes pages like this would allow us to separate the "monorepo setup" content (which makes up a large chunk of the current content, especially on CONTRIBUTING.md) from the workflow content. Setup is mostly useful at the beginning whereas workflows remain relevant and useful to consult.

Expanding on Troubleshooting content

This area is emptier than I expected. We could cover:

• Typical commands to type when switching branches to avoid issues
• Symptoms that build --watch has crashed, why this happens and what to do
• What to do when nx build cache is corrupted
• Symptoms of running CJS code in Storybook (cryptic React error in console, UI blank) and resolutions
• etc

Framework specifics

• It's not clear what the prerequisites are for running Angular sandboxes; is it just --prod or is there more?
• Any particularities of working with frameworks should be mentioned on the framework development pages if not already the case (@jonniebigodes to check)
• We could use the framework development pages to issue soft calls for contributions, especially for Angular & Vue (reproducing old bug fixes, fixing issues, helping with doc, etc.) BUT we should point to Code of Conduct in the same callout

Submitting PRs

• The site says that yarn test should pass before opening a PR; instead, we should recommend type check + prettier + build + test (which should match what is being tested in the fork CI jobs)
• There's a mention of a Work in progress label; that no longer exists
• There's a mention of 7.0.0-alpha.47; to be reworded to avoid explicit versions
• Mentions of retrofitting bug fixes to past releases should be removed, as this is at the discretion of the core team (to avoid unhealthy expectations)
• "Sync fork" links are redundant, only one needs to be preserved
• In the PR section, we should have a map of CI jobs and point to the troubleshooting / recipe section for each job so that users better understand how to locally reproduce a CI error

Reproductions

• Redundancy between dedicated repro page and repro section in code page

Templates

• Likely redundant with framework development docs
• @jonniebigodes to tell which page this should move to (contribute/frameworks api/frameworks)

On addressing desync

Some hypotheses below. I don't have a strong opinion

Remove CONTRIBUTING.md and point to the docs site instead
Pros:

• No more desync, by design!
• Reduced maintenance surface
  Cons:
• No more offline documentation
• Less easy to reach contrib docs for LLMs (is that relevant with the copilot.md file?)

Replace CONTRIBUTING.md by AGENTS.md
Pros:

• Less redundancy with the Copilot instructions file
• More likely to be updated
  Cons:
• Does not address desync at all

Set up safeguard to warn us on GitHub when CONTRIBUTING.md changes without changes to docs
Pros:

• Avoids one file being updated without the other
  Cons:
• Increases maintenance surface (one more job to maintain)
• Runtime cost for a minor concern

Prior Art

No response

Deliverables

1. Survey data on where contributors seek for information
2. A baseline of docs consultation statistics
3. A PR to refresh the docs website
4. A PR to refresh CONTRIBUTING.md
5. A PR to introduce CI jobs for forks: CI: Provide basic CI jobs for forked repositories, and disable our own jobs #32632

Risks

Adding more documentation means adding more documentation maintenance. We should ensure to limit repetition as much as possible, both across multiple file formats and within the docs pages.

Unresolved Questions

see checkboxes in RFC content above, not repeating to avoid duplication

Alternatives considered / Abandoned Ideas

No response

[tmeasday]

Mention that addon templates may not have the same native HMR support as normal stories
@tmeasday could you please clarify, from a developer's perspective, how template stories differ from regular stories?

Do you mean the DX of writing them? I'm a bit hazy on the details but the differences stem from a few things:

1. They require a special non-standard webpack loader in the sandbox, because:
   a. They are linked into the project rather than actually being files inside src (or wherever)
   b. They are written in TS, even if the project doesn't use TS []
2. They are written in a way that doesn't require any particular framework, which requires us to use a trick and store components on __TEMPLATE_COMPONENTS__ and reference them indirectly from the story file.

I couldn't tell you exactly what the implications of all that are as it has been a while since I worked on any addons :)

is it correct you need to reload SB for them to be picked up?)

You tell me :)

[Sidnioulz]

Thanks! I'll make sure to check that as we progress through doc updates :)

[Sidnioulz]

In the addon docs section, we could add recipes for e.g.

• using images in addons
• syncing a value to localStorage

[Sidnioulz]

• writing a local addon (and clarifying that it must meet the version requirements of Storybook itself on React + Emotion)