- Setting Up the Environment
- Running Tests
- Submitting a Pull Request (PR)
- Coding Style Guidelines
- Commit Message Guidelines
- Run
pnpm install
in the root of the repository to install all dependencies. - Run
pnpm link --dir ./pnpm/dev -g
to make pnpm from the repository available in the command line via thepd
command. - Run
pnpm run compile
to create an initial build of pnpm from the source in the repository. - Now you can change any source code file and run
pd [command] [flags]
to runpnpm
directly from the source code by compiling all the files without typechecking in memory. - Alternatively, for recompiling all the projects with typechecking after your changes, again run
pnpm run compile
in the root of the repository. To run a task that will recompile the projects on change, runpnpm run watch
. - Install
git-lfs
following the directions from its docs. This is required to run certain tests that require large files.- Run
git lfs pull
after installing for good measure. This is required if Git LFS was installed after cloning the pnpm git repo.
- Run
- In order to run all the tests in the repository, run
pnpm run test-main
. You may also run tests of specific projects by runningpnpm test
inside a project's directory or usingpnpm --filter <project name> test
.
Some of the e2e tests run node-gyp, so you might need to install some build-essentials on your system for those tests to pass. On Fedora, install these:
sudo dnf install make automake gcc gcc-c++ kernel-devel
You can run the tests of the project that you modified by going to the project's directory and running:
pnpm test
Alternatively, you can run it from anywhere by specifying the name of the project using the --filter
option:
pnpm --filter core test
If you want to pass options to Jest, use the pnpm run test
command and append any needed options. For instance, if you want to run a single test in a single file, run:
pnpm --filter core run test test/lockfile.ts -t "lockfile has dev deps even when installing for prod only"
Before you submit your Pull Request (PR) consider the following guidelines:
-
Search GitHub for an open or closed PR that relates to your submission. You don't want to duplicate effort.
-
Make your changes in a new git branch:
git checkout -b my-fix-branch main
-
Create your patch, following code style guidelines, and including appropriate test cases.
-
Run
pnpm changeset
in the root of the repository and describe your changes. The resulting files should be committed as they will be used during release. -
Run the full test suite and ensure that all tests pass.
-
Commit your changes using a descriptive commit message that follows our commit message conventions. Adherence to these conventions is necessary because release notes are automatically generated from these messages.
git commit -a
Note: the optional commit
-a
command line option will automatically "add" and "rm" edited files. -
Push your branch to GitHub:
git push origin my-fix-branch
-
In GitHub, send a pull request to
pnpm:main
. -
If we suggest changes then:
-
Make the required updates.
-
Re-run the test suites to ensure tests are still passing.
-
Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
git rebase main -i git push -f
-
That's it! Thank you for your contribution!
After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:
-
Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
git push origin --delete my-fix-branch
-
Check out the main branch:
git checkout main -f
-
Delete the local branch:
git branch -D my-fix-branch
-
Update your main with the latest upstream version:
git pull --ff upstream main
Use the Standard Style.
We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history.
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
The header is mandatory and the scope of the header is optional.
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.
If the commit reverts a previous commit, it should begin with revert:
, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>.
, where the hash is the SHA of the commit being reverted.
Must be one of the following:
- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- refactor: A code change that neither fixes a bug nor adds a feature
- perf: A code change that improves performance
- test: Adding missing tests
- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
The scope could be anything specifying place of the commit change. For example
plugin-example
, render-md
, etc.
The subject contains succinct description of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize first letter
- no dot (.) at the end
Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.
The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes.
Breaking Changes should start with the word BREAKING CHANGE:
with a space or two newlines. The rest of the commit message is then used for this.