为 Jupyter Notebook 做贡献

感谢您为 Jupyter Notebook 做贡献！

请务必遵循 Project Jupyter 的行为准则，以营造友好和欢迎的协作环境。

设置开发环境

注意：您需要 NodeJS 来构建扩展包。

命令 jlpm 是 JupyterLab 的固定版本 yarn，它与 JupyterLab 一起安装。您可以在下面使用 yarn 或 npm 代替 jlpm。

注意：我们建议使用 mamba 来加速环境创建。

# create a new environment
mamba create -n notebook -c conda-forge python nodejs -y

# activate the environment
mamba activate notebook

# Install package in development mode
pip install -e ".[dev,test]"

# Link the notebook extension and @jupyter-notebook schemas
jlpm develop

# Enable the server extension
jupyter server extension enable notebook

notebook 遵循单仓库结构。要一次构建所有包

jlpm build

还有一个 watch 脚本用于监视更改并自动重建应用程序

jlpm watch

要确保 notebook 服务器扩展已安装

$ jupyter server extension list
Config dir: /home/username/.jupyter

Config dir: /home/username/miniforge3/envs/notebook/etc/jupyter
    jupyterlab enabled
    - Validating jupyterlab...
      jupyterlab 3.0.0 OK
    notebook enabled
    - Validating notebook...
      notebook 7.0.0a0 OK

Config dir: /usr/local/etc/jupyter

然后使用以下命令启动 Jupyter Notebook：

jupyter notebook

Notebook 依赖项中的本地更改

上面描述的开发安装从 npmjs 获取 JavaScript 依赖项，根据 package.json 文件中的版本。但是，有时能够使用 Notebook 测试更改，而依赖项（例如 @jupyterlab 包）尚未发布。

yalc 可以帮助您在 Notebook 构建中使用本地 JavaScript 包，充当本地包仓库。

• 在您的环境中全局安装 yalc：npm install -g yalc

• 发布您的依赖包
  yalc publish，从包根目录执行。
  例如，如果您正在开发 @jupyterlab/ui-components，则必须从 path_to_jupyterlab/packages/ui-components 执行此命令。

• 在 Notebook 中依赖此本地仓库

  • 从 Notebook 根目录
    yalc add your_package：这将在主 package.json 文件中创建一个 dependencies 条目。
    在前面的示例中，它将是 yalc add @jupyterlab/ui-components。

  • Notebook 是一个单仓库，因此我们希望此依赖项作为解析（对于所有子包）而不是依赖项进行“链接”。
    最简单的方法是手动将 package.json 中的新条目从 dependencies 移动到 resolutions。

  • 使用本地依赖项构建 Notebook
    jlpm install && jlpm build

然后必须使用 jlpm build && yalc push（从包根目录）构建和推送依赖项中的更改，并使用 yarn install 从 Notebook 中获取。

警告：您需要确保 Notebook 和本地包的依赖项正确匹配，否则在构建过程中 webpack 会出现错误。
在前面的示例中，@jupyterlab/ui-components 和 Notebook 都依赖于 @jupyterlab/coreutils。我们强烈建议您依赖于相同的版本。

运行测试

要运行测试

jlpm run build:test
jlpm run test

还有一些端到端测试，用于覆盖更高级的用户交互，位于 ui-tests 文件夹中。要运行这些测试

cd ui-tests
#install required packages for jlpm
jlpm

#install playwright
jlpm playwright install

# start a new Jupyter server in a terminal
jlpm start

# in a new terminal, run the tests
jlpm test

test 脚本调用 Playwright 测试运行器。您可以通过将参数附加到命令来向 playwright 传递其他参数。例如，要在有头模式下运行测试，请使用 jlpm test --headed。

查看 Playwright 命令行参考，以获取有关可用命令行选项的更多信息。

在有头模式下运行端到端测试将触发类似以下内容

任务缓存

该仓库配置为使用 Lerna 缓存系统（通过 nx）来执行一些开发脚本。

这有助于在多次运行 jlpm run build 时加快重建速度，以避免重建磁盘上未更改的包。

您可以使用以下命令生成一个图表，以更好地了解所有包之间的依赖关系

npx nx graph

运行该命令将默认情况下打开一个浏览器标签页，其中包含一个类似于以下内容的图表

要了解有关 Lerna 缓存的更多信息

• https://lerna.node.org.cn/docs/features/cache-tasks

• https://nx.dev/features/cache-task-results

更新参考快照

通常，PR 可能会对用户界面进行更改，这会导致视觉回归测试失败。

如果您想在处理 PR 时更新参考快照，可以将以下句子作为 GitHub 评论发布

bot please update playwright snapshots

这将触发一个 GitHub Action，该 Action 将自动运行 UI 测试，并在参考快照发生更改时将新提交推送到分支。

代码风格

所有非 Python 源代码都使用 prettier 格式化，Python 源代码使用 black 格式化。当代码被修改并提交时，所有暂存的文件将使用 pre-commit git 钩子（借助 pre-commit）自动格式化。使用像 prettier 和 black 这样的代码格式化程序的好处是，它在审查拉取请求时消除了代码风格的话题，从而加快了审查过程。

只要您的代码有效，pre-commit 钩子应该会处理它的外观。 pre-commit 及其关联的钩子将在您运行 pip install -e ".[dev,test]" 时自动安装。

要手动安装 pre-commit，请运行以下命令

pip install pre-commit
pre-commit install

您可以随时手动调用 pre-commit 钩子

pre-commit run

这应该会对您的代码进行任何自动格式化，并告诉您它无法自动修复的任何错误。您也可以在文本编辑器中安装 black 集成，以便自动格式化代码。

如果您在使用 pre-commit install 设置 pre-commit 钩子之前已经提交了文件，可以使用 pre-commit run --all-files 来修复所有内容。您需要在之后自己进行修复提交。

您也可以使用 prettier npm 脚本（例如 npm run prettier 或 yarn prettier 或 jlpm prettier）来格式化整个代码库。我们建议您为您的代码编辑器安装一个 prettier 扩展，并将其配置为使用键盘快捷键或在保存时自动格式化您的代码。

默认情况下，某些钩子只在 CI 上运行，但您可以使用 --hook-stage manual 参数来调用它们。

文档

首先确保您已按照上述步骤设置了开发环境。

然后运行以下命令来构建文档

hatch run docs:build

在另一个终端窗口中，运行以下命令来提供文档

hatch run docs:serve

现在打开一个网页浏览器，并导航到 http://localhost:8000 来访问文档。

从浏览器贡献

或者，您也可以直接从网页浏览器贡献到 Jupyter Notebook，而无需设置本地环境。

• Gitpod 集成已启用。Gitpod 配置会自动构建 Jupyter Notebook 应用程序和文档。

• GitHub 的 内置编辑器 适合贡献小的修复。

• 更高级的 github.dev 编辑器可以通过在 Jupyter Notebook GitHub 存储库中按下点 (.) 键来访问。