Contributing to isort
Looking for a useful open source project to contribute to? Want your contributions to be warmly welcomed and acknowledged? Welcome! You have found the right place.
Getting isort set up for local development
The first step when contributing to any project is getting it set up on your local machine. isort aims to make this as simple as possible.
Base System Requirements:
- bash or a bash compatible shell (should be auto-installed on Linux / Mac)
- WSL users running Ubuntu may need to install Python's venv module even after installing Python.
Once you have verified that your system matches the base requirements you can start to get the project working by following these steps:
- Fork the project on GitHub.
- Clone your fork to your local file system:
git clone https://github.com/$GITHUB_ACCOUNT/isort.git
- Optionally, isolate poetry's installation from the rest of your system using the instructions on the poetry site here: https://python-poetry.org/docs/#installation
./scripts/test.shshould yield Success: no issues found
./scripts/clean.shshould yield a Safety report checking packages
./scripts/done.sh will run both clean and test in one step.
If you would instead like to develop using Docker, the only local requirement is docker. See the docker docs if you have not used docker before.
Once you have the docker daemon running and have cloned the repository, you can get started by following these steps:
A local test cycle might look like the following:
docker build ./ -t isort:latest
docker run isort
- if #2 fails, debug, save, and goto #1
docker run -it isort bashwill get you into the failed environment
docker run -v $(git rev-parse --show-toplevel):/isortwill make changes made in the docker environment persist on your local checkout. TIP: combine both to get an interacive docker shell that loads changes made locally, even after build, to quickly rerun that pesky failing test
- if #4 fails, debug, save and goto #1; you may need to specify a different
- congrats! you are probably ready to push a contribution
Making a contribution
Congrats! You're now ready to make a contribution! Use the following as a guide to help you reach a successful pull-request:
- Check the issues page on GitHub to see if the task you want to complete is listed there.
- If it's listed there, write a comment letting others know you are working on it.
- If it's not listed in GitHub issues, go ahead and log a new issue. Then add a comment letting everyone know you have it under control.
- If you're not sure if it's something that is good for the main isort project and want immediate feedback, you can discuss it here.
- Create an issue branch for your local work
git checkout -b issue/$ISSUE-NUMBER.
- Do your magic here.
- Ensure your code matches the HOPE-8 Coding Standard used by the project.
- Run tests locally to make sure everything is still working
./scripts/done.shOr if you are using Docker
docker run isort:latest
- Submit a pull request to the main project repository via GitHub.
Thanks for the contribution! It will quickly get reviewed, and, once accepted, will result in your name being added to the acknowledgments list :).
I can not tell you how thankful I am for the hard work done by isort contributors like you.