Blitz 尚在 beat 阶段! 🎉 预计会在今年的 Q3 季度发布 1.0
Back to Documentation Menu

如何贡献

Topics

Jump to a Topic

👋 我们很高兴你有兴趣帮助 Blitz!我们很乐意帮助你入门,即使你以前没有任何 开源经验 :)

第一件事

  1. 开源新手?请查阅 How to Contribute to an Open Source Project on GitHub
  2. 尝试熟悉 Blitz 行为准则
  3. 学习 社区是如何运作的

我们代码库的视频介绍

注意:该视频目前已过时,因为我们的代码库正在经历一些重要的重构。但它可能仍 然有些帮助 。观看此视频 了解整个 Blitz 代码库。这是了解各个部分以及它们如何组合在一起的好方法!

接下来做什么?

标签为 status/ready-to-work-on 的 issues 是一个很好的起点。

我们还会在适当的时候将 issues 标记为 good first issuegood second issue

如果你发现一个看起来很有趣并且没有其他人已经在处理它,请在你将要处理的问题 中发表评论。但只有在你可以几天内处理的情况下再提出此问题。

请根据需要直接在问题中或在 Discord 中提出尽可能多的问题。我们很乐意提供帮 助!

Blitz.com 网站和文档仓库也都有 ready to work on | help wanted 标签。

一直欢迎的贡献

  • 增加测试
  • 改进文档
  • 改进错误信息
  • 改进日志(例如:更简明、更好看)
  • 性能或安全改进
  • 像博客、视频和课程类的教育内容

如果你想通过其他方式做出贡献,请在 Discord 中向我们询问!

在你以任何方式作出贡献后,请通过 @all-contributors 机器人 方式将自己添加为贡献者!

我们的代码库是一个花园

Blitz 代码库就像一个社区花园。有很多美丽的植物和蔬菜,但依然很容易会发现一 些杂草!当你发现杂草时,请将它们移除 :) 始终鼓励小幅重构。如果你想进行一些 重大重构,最好先提出问题或在 Discord 中与我们联系。我们很可能会同意你的看 法。

提交 PR 后会发生什么

Blitz 维护人员通常会在几天内审核你的 PR。

如果你的 PR 更改了面向用户的代码,请确保你还对 docs 仓库进行了 PR,否则这 将阻止你的 PR 被合并。

你还需要添加测试以覆盖你所做的更改。

一旦满足所有要求并且维护者对你的代码感到满意,他们就会将其合并到 canary 分 支上。然后将包含在下一个 Blitz 版本中。

最后,你将作为官方 Blitz 贡献者添加到所有贡献者列表中。恭喜!!

项目管理

我们使用 Github 项目面板 来跟踪所有 issues 和 PRs。

提交访问

我们向任何中途定期贡献者提供对 Blitz 仓库的自由提交访问权限。这允许你将分 支直接推送到 Blitz 仓库,而无需使用 fork。

如果我们注意到他们定期做出贡献,我们通常会授予他们访问权限。但是,如果你经 常提供帮助但尚未获得访问权限,也欢迎你申请访问权限。

在主 Blitz 仓库中,代码所有者需要进行代码审查才能合并 PR。

但是在文档仓库中,一旦其他人批准了 PR,任何人都可以合并 PR。

开发配置

1. Fork blitz 仓库

2. 克隆你 fork 后的仓库

# 替换如下 USERNAME 为你的 Github 用户名
git clone git@github.com:USERNAME/blitz.git
cd blitz

3. 安装依赖

yarn

开启软件包服务器。这对于任何包开发或者示例开发来说,都必须运行

yarn dev

执行测试

Blitz.js 测试

单元测试

大多数在 packages/ 下的 Blitz 包都有 jest 单元测试。

  • 在单个包的文件夹下通过执行 yarn test 来测试这个包(例如 packages/core/
  • 通过执行 yarn testonly:packages 来在仓库根目录下运行所有的单元测试。( 请确保你运行这个之前已执行过 yarn buildyarn dev

集成测试

Blitz 集成测试位于根 test/ 文件夹中。

请确保为你的 Chrome 版本安装了 chromedriver。你可以通过如下安装它:

  • 在 Mac OS X 中执行 brew install --case chromedriver
  • 在 Windows 中执行 chocolatey install chromedriver
  • 或从 chromedriver 仓库 中手动下载与你安装的 chrome 版本匹配的版本(如果不匹配,请下载相关版本下 方的版本,而不是上方的版本)并将二进制文件添加到 <blitz-repo>/node_modules/.bin

你可以通过从仓库根目录运行 yarn test:integration 来运行所有的集成测试。 或者你可以运行 yarn testheadles 以在 Headless 模式下运行它们(这样就不会 打开网络浏览器窗口)。

要运行特定的集成测试,你可以运行以下命令:

yarn testheadless --testPathPattern "integration/queries"

其中 integration/queriestest/ 中的路径。

你可以通过在集成测试文件夹中运行 blitz dev 来手动运行应用,例如 test/integration/queries

示例应用测试 (to be deprecated)

示例应用一直作为我们的集成测试运行,但我们会将这些测试移动到上述集成测试配 置中。

要运行示例应用,首先从仓库根目录 yarn buildyarn dev。然后在另一个 窗口中,切换到示例应用文件夹,如 examples/auth/ 并运行 blitz dev

Next.js 测试

所有 Next.js 测试都在 nextjs/test 中。有很多测试,所以你可能一次只运行一 个。

要运行这些测试,请在 nextjs/ 文件夹中运行以下命令。

  • 在正常模式下运行(打开浏览器) :yarn testonly --testPathPattern "integration/basic"
  • 在 Headless 模式下运行 :yarn testheadless --testPathPattern "integration/basic"

典型的工作流程将只运行与你的更改相关的 next.js 集成测试。然后推送到 CI 并 查看是否有任何其它集成测试失败。如果有失败,则在本地运行失败的那个并解决问 题。

在应用中测试 Blitz 的开发版本

Info

目前,要测试 Blitz 的本地开发版本,你可以测试 blitz/examples 文件 夹中的一个应用程序。在那里,Blitz 依赖项将自动使用本地开发版本。我们主要使 用 authstore 示例应用。我们将它们用于开发环境测试和 Blitz 集成测试 。你还必须确保同时在 blitz 文件夹中运行 yarn dev

对于在仓库之外的应用中使用,yalc 应 该可以工作,但尚未经过测试。如果你知道如何使用 yalc,请在当前页面上做一个 PR,解释如何配置它!

同步你的 fork

git remote add upstream git@github.com:blitz-js/blitz.git
./scripts/fetchRemote.sh
git merge upstream/canary

链接 Blitz CLI(可选)

The following will link the development CLI as a local binary so you can use it anywhere for testing.

下面将开发环境 CLI,链接为本地二进制文件,以便你可以在任何地方使用它进行测 试。

yarn link-cli
yarn link blitz
// `yarn unlink blitz`
// `yarn unlink-cli`  will unlink

故障排除

如果你遇到应该在此处提交的问题,欢迎提交 PR!❤️

适用于 Linux 的 Windows 子系统

运行 yarn 时出现 node-pty 错误。通过安装 node-pty 依赖项来修复

sudo apt install -y make python build-essential

Yarn policies 错误

此 issue 与 yarn > 1.19.1 有关,如果你在你的控制台收到了这样的错误:

An unexpected error occurred: "expected workspace package to exist for \"@wessberg/rollup-plugin-ts\"

通过如下命令来修复:

yarn policies set-version 1.19.1

Git 错误

你无法 commit 吗?你是否收到类似于 yarn: command not foundstdin is not a tty 之类的错误?这可能是 Husky 的错误!尝试查看他们的 疑难解答指南

Preconstruct 错误

如果在 Windows 上尝试运行 Preconstruct 时遇到符号链接和 EPERM 错误,则可能 需要启用 Windows 开发者模式, 这样 Preconstruct 就可以创建 symlinks。

在 Windows 下缺失文件

如果你在运行 yarn build 后仍有关于丢失文件的错误,请尝试再次克隆你的存储 库,将配置 core.symlinks 设置为 true,如下所示 :git clone -c core.symlinks=true <URL>


Idea for improving this page? Edit it on GitHub.