Skip to main content

Contributing

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!

  • 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 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.

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​

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

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

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.

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:

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

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​

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.

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

  • 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.

  • 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.

  • 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.

  • Workspaces must point our repository through the repository field.

Preparing your PR to be released​

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.

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

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.

note

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

Reviewing other PRs​

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​

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

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

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

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