forked from s_ranjbar/city_retrofit
100 lines
5.1 KiB
Markdown
100 lines
5.1 KiB
Markdown
# Contributing guidelines
|
|
|
|
## Push Request Checklist
|
|
|
|
Before sending your pull requests, make sure you completed this checklist:
|
|
|
|
- Read to the end [this document](CONTRIBUTING_EXTERNALS.md).
|
|
- Read [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
- Check if your changes are consistent with the [Guidelines](CONTRIBUTING_EXTERNALS.md#user-content-general-guidelines-and-philosophy-for-contribution).
|
|
- Check if your changes are consistent with the [Coding Style](CONTRIBUTING_EXTERNALS.md#user-content-coding-style).
|
|
- Manually test your code and add [Unit Tests](CONTRIBUTING_EXTERNALS.md#user-content-testing-best-practices).
|
|
- Be sure that you didn't brake anything by running all unit tests in folder unittests (right click on the folder and click on the green play).
|
|
- [Document your work](CONTRIBUTING_EXTERNALS.md#user-content-documentation).
|
|
|
|
## How to become a contributor and submit your own code
|
|
|
|
### Contributor License Agreements
|
|
|
|
CERC Libs is an [LGPL licensed](LICENSE.md) software, so even if we'd love to accept your patches, before we can take them,
|
|
please be sure that you are the intellectual property owner of your code and that do you fully understand and respect our software license.
|
|
|
|
***NOTE***: Only source code that you own will go into the main repository.
|
|
|
|
### Contributing code
|
|
|
|
If you made any changes in your own project, just push them to git. You are the owner, you are the manager.
|
|
|
|
To do so, first, commit your changes by clicking on the green check at the top-right corner of Pycharm. Add a comment that explains briefly your changes.
|
|
Then, pull by clicking on the blue arrow to be sure that there are no conflicts between your version (local) and the one in gitlab (remote).
|
|
Once the conflicts are solved and the merge in local is done, push the changes by clicking on the green arrow.
|
|
|
|
If you have improvements to CERC Libs or want to extend the functionality, please send us your pull request as seen at [git pull request documentation](https://git-scm.com/docs/git-request-pull).
|
|
Or ASK GUILLE!!!!
|
|
|
|
Once the pull requests are approved and pass continuous integration checks, a team member will merge your changes on CERC Libs, and your code will become an integral part of Insel4D platform.
|
|
|
|
If you prefer to contribute, instead of adding new functionality, you can also take a look at our ticket system and try to fix any of the listed issues.
|
|
??????????? SURE WE WANT THIS?
|
|
|
|
### Contribution guidelines and standards
|
|
|
|
Before sending your pull request for review, make sure your changes are consistent with the guidelines, and follow the CERC Libs coding style.
|
|
|
|
#### General guidelines and philosophy for contribution
|
|
|
|
* Include unit tests when you contribute new features, as they help to:
|
|
* Prove that your code works correctly.
|
|
* Guard against future breaking changes to lower the maintenance cost.
|
|
|
|
* Bug fixes also generally require unit tests, because the presence of bugs usually indicates insufficient test coverage.
|
|
* Keep backward compatibility in mind when you change code in CERC Libs, and if you need to brake the backward compatibility, please ensure that you:
|
|
* Clearly indicate which features are affected by your changes.
|
|
* Technical reasons for the changes.
|
|
??????????? SURE WE WANT THIS?
|
|
|
|
|
|
* Tests should follow the
|
|
[testing best practices](CONTRIBUTING_EXTERNALS.md#user-content-testing-best-practices)
|
|
guide.
|
|
* [Document your contribution](CONTRIBUTING_EXTERNALS.md#user-content-documentation)
|
|
|
|
#### License
|
|
|
|
Include a small header with contact information and the code license at the top of any new file like in the following example.
|
|
|
|
"""
|
|
Name module
|
|
SPDX - License - Identifier: LGPL - 3.0 - or -later
|
|
Copyright © 2022 Concordia CERC group
|
|
Project Coder name mail@concordia.ca
|
|
"""
|
|
|
|
|
|
#### Coding style
|
|
|
|
Changes to CERC Libs python code should conform to our coding style [Cerc Python Style Guide](PYGUIDE.md)
|
|
|
|
As a general basis, all contributions need to be focused on the concept of code clarity and use pylint to check your Python changes.
|
|
To install pylint and check your files against Cerc custom style definition:
|
|
|
|
To install `pylint` and check a file
|
|
with `pylint` against Cerc custom style definition:
|
|
|
|
```bash
|
|
pip install pylint
|
|
pylint --rcfile=pylintrc myfile.py
|
|
```
|
|
|
|
#### Testing best practices
|
|
|
|
Before any pull request, the code must been manually and automatically tested to ensure at least some quality minimum. There are a few practices for unit tests that we believe are important, so we encourage you to follow it.
|
|
|
|
* The test should be self-contained, which implies that your tests will prepare and clean up everything before and after the test execution.
|
|
* We encourage you to create if possible functional tests that cover the complete workflow of the implemented functionality.
|
|
* Maximize your code coverage by ensuring that you are testing as much of your code as possible.
|
|
|
|
#### Documentation
|
|
|
|
In case of new functionality, a general overview, configuration, installation, and user manuals need to be provided by the developer; this will provide an excellent starting point for all the future users and help you detect any inconsistencies in your design.
|