We are glad and thankful that you want to contribute to OpenWISP.
Please read these guidelines carefully, it will help you and us to save precious time later.
It won’t hurt to join our main communication channels and introduce yourself; you can take advantage of your introduction to share feedback, share your OpenWISP derivative work, ask questions or announce your intentions.
Look for open issues¶
Check out the OpenWISP Contributor’s Board, this is a kanban board integrated with github where we place the most important issues we are working on.
If there’s anything you don’t understand regarding the board, don’t hesitate to ask questions in our general chat.
Once you have chosen an issue to work on, read the
README of the
repository in which the issue has been opened and follow the setup
instructions, each module has its own specific instructions and we highly
suggest you to read as much as possible.
How to commit your changes properly¶
Our main development branch is master, it’s our central development branch.
you should open a pull request on github. The pull request will be merged only once the test build completes successfully (automated tests, code coverage check, style checks, etc.) and after project maintainers have reviewed and tested it.
1. Branch naming guidelines¶
Create a new branch for your patch, use a self-descriptive name, eg:
git pull origin master # if there's an issue your patch addresses git checkout -b issues/48-issue-title-shortened # if there is no issue for your branch, (we suggest creating one anyway) # use a descriptive name git checkout -b autoregistration
2. Commit message style guidelines¶
Please follow our commit message style conventions.
If the issue is present on Github, use following commit style:
[module/file/feature] Short description #<issue-number> Long description here. Fixes #<issue-number>
Here’s a real world commit message example from one of our modules:
[admin] Fixed VPN context in preview #57 Fortunately it was just a frontend JS issue. The preview instance was getting the UUID of the Device object instead of the Config object, and that prevented the system from finding the associated VPN and fill the context VPN keys correctly. Fixes #57
Moreover, keep in mind the following guidelines:
- commits should be descriptive in nature, the message should explain the nature of the change
- make sure to follow the code style used in the module you are contributing to
- before committing and pushing the changes, test the code both manually and automatically with the automated test suite if applicable
- after pushing your branch code, make a pull-request of that corresponding change of yours which should contain a descriptive message and mention the issue number as suggested in the example above
- make sure to send one pull request for each feature. Each feature should contain one commit. If you make multiple commits for a single feature/bug-fix, squash them to a single commit providing an informative commit message after you are done with the required changes.
- in case of big features in which multiple related features/changes needs to be implemented, multiple commits (one commit per feature) in a single PR can be accepted.
3. Pull-Request guidelines¶
After pushing your changes to your fork, prepare a new Pull Request (from now on we will shorten it often to just PR):
- from your forked repository of the project select your branch and click “New Pull Request”
- check the changes tab and review the changes again to ensure everything is correct
- write a concise description of the PR, if an issue exists for
- after submitting your PR, check back again whether your PR has passed our required tests and style checks
- if the tests fail for some reason, try to fix them and if you get stuck seek our help on our communication channels
- if the tests pass, maintainers will review the PR and may ask you to improve details or changes, please be patient: creating a good quality open source project takes a bit of sweat and effort; ensure to follow up with this type of operations
- once everything is fine with us we’ll merge your PR
4. Avoiding unnecessary changes¶
- while making changes to the required files, then saving it and comitting it, different contributors often find that there occur same changes that they have not made and those changes gets committed with the desired change that the person wants to make
- these unnecessary changes should be evaluated first and then the commit should be made
- these changes generally occur due to different settings and customizations of your editor that you are working with. These changes are produced on their own as soon as you save a file. Examples are - Introducing new lines, removing and adding spaces, etc
- to avoid such changes please check your editor settings first. If this sort of behaviour persists please use any command line editor like VIM, etc
Coding Style Conventions¶
1. Python code conventions¶
OpenWISP follows PEP 8 – Style Guide for Python Code and uses the following automatic tools to check code conventions:
- flake8 is used to
automatically check the quality of the python code being committed,
each python repo has either a
flake8configuration defined in
runflake8script that you can launch with
- isort is used in order
to sort import in a specifc predictable order; each python repo has
runisortscript that you can launch with
- Lastly, black is used to automatically format the code according to our conventions.
For your convenience, we provide the following scripts available in the openwisp-utils repository:
openwisp-qa-formatformats your Python code according to the OpenWISP standards.
openwisp-qa-checkis run by Travis CI to check your Python code quality and style standard. You can run it yourself as well in order to detect mistakes before Travis does.
If you want to learn more about our usage of python and django, we suggest reading Hacking OpenWISP: Python and Django
If you follow these guidelines closely your contribution will have a very positive impact on the OpenWISP project.
Thanks a lot for your patience.