Contributing to PDM#
First off, thanks for taking the time to contribute! Contributions include but are not restricted to:
- Reporting bugs
- Contributing to code
- Writing tests
- Writing documentation
The following is a set of guidelines for contributing.
A recommended flow of contributing to an Open Source project#
This section is for beginners to OSS. If you are an experienced OSS developer, you can skip this section.
- First, fork this project to your own namespace using the fork button at the top right of the repository page.
- Clone the upstream repository to local:
1 2 3
git clone https://github.com/pdm-project/pdm.git # Or if you prefer SSH clone: git clone [email protected]:pdm-project/pdm.git
- Add the fork as a new remote:
git remote add fork https://github.com/yourname/pdm.git git fetch fork
forkis the remote name of the fork repository.
- Don't modify code on the main branch, the main branch should always keep track of origin/main.
To update main branch to date:
1 2 3
- Create a new branch based on the up-to-date main branch for new patches.
- Create a Pull Request from that patch branch.
To make sure the test suites can run correctly, you need to install Git LFS, then
1 2 3
Then, you need to install base dependencies in a venv. Make sure your
pip is newer than
21.3 to install PDM in
You are free to create a virtualenv with either
venv module or
virtualenv tool for the development. If you are doing
so, you may also need to set
pdm config use_venv true after installation is done.
Now, all dependencies are installed into the Python environment you choose, which will be used for development after this point.
The test suite is still simple and needs expansion! Please help write more test cases.
You can also run your test suite against all supported Python version using
tox with the
You can either run it by yourself with:
pre-commit for linting. Install
pre-commit first, then:
black for code style and
isort for sorting import statements. If you are not following them,
the CI will fail and your Pull Request will not be merged.
When you make changes such as fixing a bug or adding a feature, you must add a news fragment describing
your change. News fragments are placed in the
news/ directory, and should be named according to this pattern:
feature: Features and improvements
bugfix: Bug fixes
refactor: Code restructures
doc: Added or improved documentation
dep: Changes to dependencies
removal: Removals or deprecations in the API
misc: Miscellaneous changes that don't fit any of the other categories
The contents of the file should be a single sentence in the imperative
mood that describes your changes. (e.g.,
Deduplicate the plugins list. ) See entries in the Change Log for more examples.
Preview the documentation#
If you make some changes to the
docs/ and you want to preview the build result, simply do:
Once all changes are done and ready to release, you can preview the changelog contents by running:
Make sure the next version and the changelog are as expected in the output.
Then cut a release on the main branch:
GitHub action will create the release and upload the distributions to PyPI.
Read more options about version bumping by
pdm run release --help.