代码贡献

为 Storybook 的单仓库 贡献新功能或错误修复。 此页面概述了如何设置环境以贡献代码。

先决条件

• 确保你已安装 Node 版本 18（建议：v18.16.0）。
• 如果你使用的是 Windows，请确保使用 Windows Subsystem for Linux (WSL)。

初始设置

首先 fork Storybook 的单仓库，并将其克隆到本地。

git clone https://github.com/your-username/storybook.git
cd storybook

Storybook 使用 Yarn 包管理器。 使用 Corepack 设置与 Storybook 一起使用的正确版本。

corepack enable

运行你的第一个沙盒

Storybook 的开发发生在一组沙盒中，这些沙盒是对应于不同用户设置的模板化 Storybook 环境。 在每个沙盒中，我们注入了一组通用的故事，使我们能够在所有此类环境中测试核心功能和附加组件。

要在本地运行沙盒，可以使用 start 命令

yarn start

它将安装所需的先决条件，构建代码，创建并链接一个基于 Vite React 设置的入门示例，最后启动 Storybook 服务器。

如果一切顺利，你应该会看到沙盒正在运行。

运行不同的沙盒模板

默认情况下，start 命令被配置为初始化一个基于 Vite 的 React 模板。 如果你打算在不同的渲染器上工作，你也可以这样做。 首先，运行以下 task 命令

yarn task

当出现提示时，尽可能准确地回答问题，以便 Storybook 能够确定你的目标。 回答完这些问题后，如果你需要重新运行，你应该会看到包含你选择的选项的完整命令。

运行测试

成功运行 第一个沙盒 后，你应该已经有一个在本地机器上构建的完全功能的 Storybook 版本。 在进行任何代码更改之前，验证一切正常至关重要，特别是测试套件。

运行以下命令以执行测试

yarn test

开始开发

现在你已经 验证了你的设置，是时候开始写代码了。 最简单的方法是在一个终端窗口中运行一个沙盒，并在另一个终端窗口中运行交互式构建过程。

假设你仍在运行运行 yarn start 命令后初始化的基于 Vite 的 React 沙盒，打开一个新的终端窗口，并导航到 Storybook 单仓库的 code 目录。 然后，通过运行以下命令为你的贡献创建一个新分支

git checkout -b my-first-storybook-contribution

最后，使用以下命令运行构建过程

yarn build

当系统提示您以 watch 模式启动构建过程时，请回答 **yes** 以交互模式进行开发。之后，选择要构建的软件包。例如，如果您要为 @storybook/addon-docs 开发一项功能，您可能需要同时选择 @storybook/addon-docs 和 @storybook/components。

如果您要做的工作会影响 Preview（最里面的 Storybook iframe，其中显示故事），它会在您保存后一到两秒钟自动刷新。

否则，如果它影响 Manager（最外面的 Storybook iframe，其中显示附加组件），您需要在保存后手动刷新。

检查您的工作

编码完成后，根据需要添加文档和测试。这简化了 PR 审查流程，这意味着您的代码将更快地合并。

添加故事

向我们的套件中添加一个故事或一组通用故事可以帮助您测试您的工作。

假设您正在处理其中一个 基本附加组件，则可能已经存在一组完整的故事。检查附加组件的 template/stories 目录，该目录记录了它的工作方式，并在其中添加您的故事。

如果您正在修改与特定渲染器相关的内容（例如，React、Vue 3 等），它也将具有类似的 template/stories 目录，您需要在其中添加您的故事。

添加测试

单元测试确保 Storybook 不会意外中断。如果您的代码可能以不明显的方式发生回归，请将单元测试包含在您的拉取请求中。使用以下命名约定

+-- parentFolder
|   +-- [filename].ts
|   +-- [filename].test.ts

端到端测试 (e2e)

Storybook 的单仓库被设置为依赖于 CI 期间使用 Playwright 进行的端到端测试。为了帮助进行测试，我们鼓励您在提交贡献之前运行此测试套件。

要针对沙箱运行 e2e 测试，可以使用 e2e-tests 任务

yarn task --task e2e-tests --template=react-vite/default-ts --start-from=auto

如果存在问题，您想对其进行调试，可以传递 DEBUG=1 环境变量，Playwright 将以 watch 模式运行。

DEBUG=1 yarn task --task e2e-tests --template=react-vite/default-ts --start-from=auto

提交拉取请求

在提交您的贡献之前，最后一次使用以下内容运行测试套件

yarn test

这样做可以防止出现最后一刻的错误，并且是提交拉取请求后更快地合并您的贡献的好方法。如果不这样做，将导致维护人员之一用 **正在进行的工作** 标签标记拉取请求，直到所有测试通过。

目标 next 分支

测试套件完成后，就可以提交、推送并针对 Storybook 的 next（默认）分支打开拉取请求。此分支是所有活动开发发生的地方，与最新的预发布版本相关联（例如，7.0.0-alpha.47）。

如果您的贡献侧重于错误修复，并且您希望它在下一个稳定版本中发布，请在拉取请求描述中说明这一点。如果它看起来是非破坏性的，并且修复了一个关键错误，我们会尝试对其进行修补。

使用分支时有用的资源

• 同步分支
• 将上游存储库合并到您的分支

重现作业失败

创建 PR 后，如果 CI 作业之一失败，在检查该作业的日志时，您将看到它打印了一条消息，说明如何在本地重现该任务。通常情况下，这涉及针对正确的模板运行该任务

yarn task --task e2e-tests --template=react-vite/default-ts --start-from=install

通常最好从 install 任务开始，以确保您的本地代码完全是最新的。如果您重现了错误，您可以尝试进行修复，使用 build 编译它们，然后使用 --start-from=auto 重新运行该任务。

如何处理重现

我们鼓励错误报告包含重现。就像可以针对单仓库中的示例项目交互式开发一样，也可以针对重现存储库进行开发。

为此，请在单仓库的根目录中运行以下命令

npx storybook@next link https://github.com/your-username/your-project.git

此命令创建了一个项目 ../storybook-repros/your-project，并自动将其链接到您的本地 Storybook 代码。连接后，您应该能够运行 Storybook 并按 上面 所述进行开发。

如果您已经在本地计算机上拥有一个重现，您可以使用 --local 标志将其类似地链接到您的单仓库开发设置

npx storybook@next link --local /path/to/local-repro-directory

开发模板

第一步是向 code/lib/cli/src/sandbox-templates.ts 添加一个条目，这是所有重现模板的主列表

'cra/default-js': {
    name: 'Create React App (Javascript)',
    script: 'npx create-react-app .',
    inDevelopment: true,
    expected: {
      framework: '@storybook/cra',
      renderer: '@storybook/react',
      builder: '@storybook/builder-webpack5',
    },
  },

在 PR 合并之前添加 inDevelopment 标志（您可以用第二个 PR 快速跟踪它以删除该标志），因为它将使开发过程变得更加容易。

key cra/default-js 由两部分组成

• 前缀是用于生成重现应用程序的工具
• 后缀是修改默认安装的选项，例如特定版本或选项

script 字段用于生成应用程序环境。 . 参数是“当前工作目录”，它根据键自动生成（例如 repros/cra/default-js/before-storybook）。 {{beforeDir}} 键也可以使用，它将被该目录的路径替换。

其余字段不言自明

skipTasks 字段存在是因为一些沙盒可能在特定任务中暂时无法正常工作，但我们可能仍然希望运行其他任务。例如，在我们的控制范围之外引入了一个错误，该错误仅在 test-runner 任务中失败。

name 字段应包含模板的易于理解的名称/描述。

expected 字段反映了我们期望 sb init 生成的框架/渲染器/构建器。这对于生成沙盒时的断言很有用。如果模板使用不同的预期框架生成，例如，它将失败，作为检测回归的一种方式。

运行沙盒

如果您的模板具有 inDevelopment 标志，它将作为沙盒过程的一部分（本地）生成。您可以使用以下命令创建沙盒，其中 <template-key> 被选定模板的 id 替换，例如 cra/default-js

yarn task --task dev --template <template-key> --start-from=install

具有 inDevelopment 的模板将自动使用 --no-link 标志运行，因为本地模板生成需要它。

PR 合并后，模板将在每晚生成，您可以移除 inDevelopment 标志，沙盒将从我们的模板仓库中拉取代码。

故障排除

了解更多关于为 Storybook 做贡献的信息

• RFC 流程 用于编写功能请求
• 功能和错误修复代码
• 框架 从新的框架开始
• 文档 用于文档改进、错别字和澄清
• 示例 用于新的代码片段和示例