Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
Fork and clone the repository, then:
cd mkdocstrings make setup
If it fails for some reason, you'll need to install PDM manually.
You can install it with:
python3 -m pip install --user pipx pipx install pdm
Now you can try running
make setup again,
You now have the dependencies installed.
make help to see all the available actions!
This project uses duty to run tasks. A Makefile is also provided. The Makefile will try to run certain tasks on multiple Python versions. If for some reason you don't want to run the task on multiple Python versions, you can do one of the following:
export PYTHON_VERSIONS=: this will run the task with only the current Python version
- run the task directly with
pdm run duty TASK
The Makefile detects if a virtual environment is activated,
make will work the same with the virtualenv activated or not.
- create a new branch:
git checkout -b feature-or-bugfix-name
- edit the code and/or the documentation
make formatto auto-format the code
make checkto check everything (fix any warning)
make testto run the tests (fix any issue)
- if you updated the documentation or the project dependencies:
- go to http://localhost:8000 and check that everything looks good
- follow our commit message convention
If you are unsure about how to fix or ignore a warning, just let the continuous integration fail, and we will help you during the review.
Don't bother updating the changelog, we will take care of this.
Commit message convention¤
Commits messages must follow the Angular style:
<type>[(scope)]: Subject [Body]
Scope and body are optional. Type can be:
build: About packaging, building wheels, etc.
chore: About packaging or repo/files management.
ci: About Continuous Integration.
docs: About documentation.
feat: New feature.
fix: Bug fix.
perf: About performance.
refactor: Changes that are not features or bug fixes.
style: A change in code style/format.
tests: About tests.
Subject (and body) must be valid Markdown. If you write a body, please add issues references at the end:
Body. References: #10, #11. Fixes #15.
Pull requests guidelines¤
Link to any related issue in the Pull Request message.
During the review, we recommend using fixups:
# SHA is the SHA of the commit you want to fix git commit --fixup=SHA
Once all the changes are approved, you can squash your commits:
git rebase -i --autosquash master
git push -f
If this seems all too complicated, you can push or force-push each new commit, and we will squash them ourselves if needed, before merging.