Skip to main content

贡献

感谢你来到这里！Yarn 非常重视成为社区项目，我们依赖你的帮助就像你依赖我们的帮助一样。为了帮助你帮助我们，我们投资了一个基础设施和文档，这将使对 Yarn 的贡献变得非常容易。如果你对我们可以改进的地方有任何反馈，请打开问题进行讨论！

¥Thanks for being here! Yarn gives a lot of importance to being a community project, and we rely on your help as much as you rely on ours. In order to help you help us, we've invested in an infra and documentation that should make contributing to Yarn very easy. If you have any feedback on what we could improve, please open an issue to discuss it!

打开问题​

¥Opening an issue

问题必须遵循问题模板。确保遵循所有内容，特别注意复制。如果我们无法重现你的问题，我们将不会解决它。

¥Issues have to follow the issue template. Make sure to follow everything, with a special attention for the reproduction. If we can't reproduce your problem, we won't solve it.

你能提供什么帮助？​

¥How can you help?

  • 查看我们的文档！我们通常不是以英语为母语的人，我们的语法可能有点不对。任何可以帮助我们的文档更易于理解的帮助都会得到赞赏！

    ¥Review our documentation! We often aren't native english speakers, and our grammar might be a bit off. Any help we can get that makes our documentation more digestible is appreciated!

  • 在你当地的聚会上谈论 Yarn！即使我们的用户也并不总是知道我们的某些功能。学习，然后与你自己的圈子分享你的知识！

    ¥Talk about Yarn in your local meetups! Even our users aren't always aware of some of our features. Learn, then share your knowledge with your own circles!

  • 帮助我们的基础设施！总是有一些小的改进要做：更快地运行测试，统一测试名称，改进版本号的设置方式，...

    ¥Help with our infra! There are always small improvements to do: run tests faster, uniformize the test names, improve the way our version numbers are setup, ...

  • 编写代码！我们想要实现的功能太多了，但实际实现的时间却太少……任何你能提供的帮助都会得到赞赏，并且你会很高兴知道你的工作帮助了数百万开发者！

    ¥Write code! We have so many features we want to implement, and so little time to actually do it... Any help you can afford will be appreciated, and you will have the satisfaction to know that your work helped literally millions of developers!

寻找要做的工作​

¥Finding work to do

可能很难知道从哪里开始新的代码库。为了对此有所帮助，我们尝试用标签标记各种问题，旨在高亮我们认为不需要太多上下文的问题：

¥It might be difficult to know where to start on a fresh codebase. To help a bit with this, we try to mark various issues with tags meant to highlight issues that we think don't require as much context as others:

  • Good First Issue 通常是有限范围的独立功能，是了解 Yarn 内部工作原理的好方法。

    ¥Good First Issue are typically self-contained features of a limited scope that are a good way to get some insight as to how Yarn works under the hood.

  • 需要帮助 是不需要大量上下文的问题，但影响也小于需要大量上下文的问题，因此没有核心维护者有足够的带宽来处理它们。

    ¥Help Wanted are issues that don't require a lot of context but also have less impact than the ones who do, so no core maintainer has the bandwidth to work on them.

最后，请随时访问我们的 Discord 通道 以寻求帮助和指导。我们总是很高兴看到新鲜​​血液，并将尽最大努力帮助你使你的第一个开源贡献取得成功！

¥Finally, feel free to pop on our Discord channel to ask for help and guidance. We're always happy to see new blood, and will help you our best to make your first open-source contribution a success!

编写你的功能​

¥Writing your feature

我们的存储库设置方式是，在其中调用 yarn 将始终使用 TypeScript 源本身 - 你不必重建任何东西即可将你的更改应用到那里（我们使用 esbuild 根据需要自动转译文件）。缺点是它比常规 Yarn 慢，但改进的开发者体验非常值得。

¥Our repository is set up in such a way that calling yarn inside it will always use the TypeScript sources themselves - you don't have to rebuild anything for your changes to be applied there (we use esbuild to automatically transpile the files as we require them). The downside is that it's slower than the regular Yarn, but the improved developer experience is well worth it.

yarn install # Will automatically pick up any changes you made to sources

测试你的代码​

¥Testing your code

我们目前有两个测试套件，用于不同的目的。第一个是单元测试，可以通过在存储库中的任何位置运行以下命令来触发：

¥We currently have two testsuites, built for different purposes. The first one is unit tests and can be triggered by running the following command from anywhere within the repository:

yarn test:unit

虽然具有严格 JS 接口契约的各种子组件通过单元测试进行测试（例如可移植 shell 库或我们交付的各种实用程序库），但 Yarn 作为一个整体依赖于集成测试。它们更接近我们用户的体验，在重构应用时，它们让我们更有信心一切都会按计划进行。这些测试可以通过运行以下命令来触发（同样，从存储库中的任何位置）：

¥While various subcomponents that have a strict JS interface contract are tested via unit tests (for example the portable shell library, or the various util libraries we ship), Yarn as a whole relies on integration tests. Being much closer to what our users experience, they give us a higher confidence when refactoring the application that everything will work according to plan. Those tests can be triggered by running the following command (again, from anywhere within the repository):

yarn build:cli
yarn test:integration

请注意，由于我们希望避免在每个 Yarn 调用中添加 esbuild 开销，因此需要预先构建 CLI 才能运行集成测试 - 这就是 yarn build:cli 命令的用途。不幸的是，这意味着如果你希望集成测试能够获取你的更改，则需要在每次修改后重建 CLI。

¥Note that because we want to avoid adding the esbuild overhead to each Yarn call the CLI will need to be prebuilt for the integration tests to run - that's what the yarn build:cli command is for. This unfortunately means that you will need to rebuild the CLI after each modification if you want the integration tests to pick up your changes.

单元测试和集成测试都使用 Jest，这意味着你可以使用 -t 标志（或简单的文件路径）过滤要运行的测试：

¥Both unit tests and integration tests use Jest, which means that you can filter the tests you want to run by using the -t flag (or simply the file path):

yarn test:unit yarnpkg-shell
yarn test:integration -t 'it should correctly install a single dependency that contains no sub-dependencies'

如果你需要编写测试（如果你添加功能或修复错误，你肯定会这样做😉），它们位于以下目录中：

¥Should you need to write a test (and you certainly will if you add a feature or fix a bug 😉), they are located in the following directories:

makeTemporaryEnv 实用程序会为你的测试上下文生成一个非常基本的临时环境。第一个参数将用于生成 package.json 文件，第二个参数用于生成 .yarnrc.yml 文件，第三个参数是临时环境创建后将运行的回调。

¥The makeTemporaryEnv utility generates a very basic temporary environment just for the context of your test. The first parameter will be used to generate a package.json file, the second to generate a .yarnrc.yml file, and the third is the callback that will be run once the temporary environment has been created.

格式化代码​

¥Formatting your code

在提交代码以供审核之前，请使用以下命令从存储库中的任何位置确保你的代码格式正确：

¥Before submitting your code for review, please make sure your code is properly formatted by using the following command from anywhere within the repository:

yarn test:lint

我们使用 ESLint 来检查这一点，因此使用 --fix 标志将导致 ESLint 尝试自动更正可能留在代码中的大多数错误：

¥We use ESLint to check this, so using the --fix flag will cause ESLint to attempt to automatically correct most errors that might be left in your code:

yarn test:lint --fix

检查约束​

¥Checking Constraints

我们使用 constraints 在整个存储库中强制执行各种规则。它们在 constraints.pro file 内部声明，其用途通过注释记录下来。

¥We use constraints to enforce various rules across the repository. They are declared inside the constraints.pro file and their purposes are documented with comments.

可以使用 yarn constraints 检查约束，并使用 yarn constraints --fix 进行修复。一般而言：

¥Constraints can be checked with yarn constraints, and fixed with yarn constraints --fix. Generally speaking:

  • 工作区不得依赖于冲突的依赖范围。在安装依赖时使用 -i,--interactive 标志并选择 "重用"，你就不必处理此规则。

    ¥Workspaces must not depend on conflicting ranges of dependencies. Use the -i,--interactive flag and select "Reuse" when installing dependencies and you shouldn't ever have to deal with this rule.

  • 工作区不得依赖于可用工作区的非工作区范围。在安装依赖时使用 -i,--interactive 标志并选择 "重用" 或 "附加"，你就不必处理此规则。

    ¥Workspaces must not depend on non-workspace ranges of available workspaces. Use the -i,--interactive flag and select "Reuse" or "Attach" when installing dependencies and you shouldn't ever have to deal with this rule.

  • 作为标准包或插件一部分的工作区必须具有特定的构建脚本。没有的必须在 constraints.pro 文件中用 inline_compile 声明。

    ¥Workspaces that are part of the standard bundle or plugins must have specific build scripts. The ones that aren't, must be declared inside the constraints.pro file with inline_compile.

  • 工作区必须通过 repository 字段指向我们的存储库。

    ¥Workspaces must point our repository through the repository field.

准备发布 PR​

¥Preparing your PR to be released

为了跟踪需要发布哪些包，我们使用 以下文档 中描述的工作流程。总而言之，你必须在你进行的每个 PR 上运行 yarn version check --interactive，并选择应再次发布哪些包以使你的更改生效（以及发布到哪个版本）（如果有）。

¥In order to track which packages need to be released, we use the workflow described in the following document. To summarize, you must run yarn version check --interactive on each PR you make, and select which packages should be released again for your changes to be effective (and to which version), if any.

你可以使用 yarn version check 检查是否已正确设置所有内容。

¥You can check if you've set everything correctly with yarn version check.

如果你预计必须再次发布包但 Yarn 不提供此选项，请首先检查本地分支的名称是否为 master。如果是这种情况，Yarn 可能无法检测到你的更改（因为它将针对 master（即你自己）执行此操作）。运行以下命令：

¥If you expect a package to have to be released again but Yarn doesn't offer you this choice, first check whether the name of your local branch is master. If that's the case, Yarn might not be able to detect your changes (since it will do it against master, which is yourself). Run the following commands:

git checkout -b my-feature
git checkout -
git reset --hard upstream/master
git checkout -
yarn version check --interactive

如果失败了，而你不知道原因，请随时联系维护者，我们会尽力帮助你。

¥If it fails and you have no idea why, feel free to ping a maintainer and we'll do our best to help you.

注意

如果你修改其中一个 默认插件，你还需要增加 @yarnpkg/cli。

¥If you modify one of the default plugins, you will also need to bump @yarnpkg/cli.

查看其他 PR​

¥Reviewing other PRs

如果你发现明显的错误，欢迎你发表评论，但如果你不是成员，请不要批准 PR。在开源社区中，它通常被视为 错误形式。

¥You're welcome to leave comments if you spot glaring bugs, but do not approve PRs if you're not a member. It's generally seen as bad form in the open source community.

编写文档​

¥Writing documentation

我们使用 Docusaurus 从 mdx 源文件生成 HTML 页面。

¥We use Docusaurus to generate HTML pages from mdx sources files.

我们的网站存储在 packages/docusaurus 目录中。你可以通过修改 docs 文件夹中相应的 .mdx 文件来更改页面。例如，你将编辑此页面 此处。

¥Our website is stored within the packages/docusaurus directory. You can change a page by modifying the corresponding .mdx file in the docs folder. For example, you'd edit this very page here.

然后运行以下命令生成本地服务器并查看你的更改：

¥Then run the following command to spawn a local server and see your changes:

yarn start

对文档的样子满意后，只需提交本地更改并打开 PR。Netlify 将获取你的更改并创建一个新的预览供所有人查看：

¥Once you're happy with what the documentation looks like, just commit your local changes and open a PR. Netlify will pick up your changes and create a fresh preview for everyone to see:

分析​

¥Profiling

运行以下命令来生成未压缩的包：

¥Run the following command to generate an unminified bundle:

yarn build:cli --no-minify

在 packages/yarnpkg-cli/bundles/yarn.js 上对生成的包使用分析器。这是一个使用 Node.js 内置分析器的示例：

¥Use a profiler on the generated bundle at packages/yarnpkg-cli/bundles/yarn.js. Here is an example which uses the Node.js built-in profiler:

YARN_IGNORE_PATH=1 node --prof packages/yarnpkg-cli/bundles/yarn.js