- Git
- Clone https://github.com/greco-project/pvcompare.git or
git@github.com:greco-project/pvcompare.git
(SSH) and install the cloned repository using pip with the developer extras:
cd pvcompare
pip install -r requirements.txt
pip install -e .[dev]
Development of a feature for this repository should be aligned with the workflow described by Vincent Driessen.
Here is the minimal procedure you should follow :
Create an issue on the github repository, describing the problem you will then address with your feature/fix. This is an important step as it forces one to think about the issue (to describe an issue to others, one has to think it through first).
-
Create a separate branch from
dev
(make sure you have the latest version ofdev
), to work ongit checkout -b feature/description_of_feature dev
The convention is to start the branch name with its functionality, e.g.
feature/
orfix/
. The second part describes shortly what the feature/fix is about. -
Try to follow these conventions for commit messages:
- Keep the subject line short (i.e. do not commit more than a few changes at the time)
- Use imperative for commit messages
- Do not end the commit message with a period
-
Push your local branch on the remote server immediately so that everyone knows you are working on it, you are also encouraged to create a draft pull request (see Step 4).
After creating a pull request (step 4) tests will run automatically but you can also run them locally - this is especially helpful in case a tests fails and you need debugging for finding the error. To install all packages required for the integration tests locally run:
pip install -e .[dev]
Run tests locally by:
pytest
If a test fails, it is only due to what you changed (the test must passed before the code is merged, so you know that the tests were passing before you start working on your branch). The test names and error messages are there to help you find the error, please read them to try to debug yourself before seeking assistance.
Follow the steps of the github help to create the PR.
Please note that you PR should be directed from your branch (for example feature/myfeature
) towards the branch dev
.
You can start with a draft pull request (see step 6 of github help) to let the other developers know that you are working on the issue and unblock if for review once your feature is finished.
Please follow the indications in the pull request template and update the appropriate checkboxes.
Once you are satisfied with your PR you should ask someone to review it. Before that please lint
your code with Black (run black . --exclude docs/
).
The documentation of pvcompare is compiled with the content of the folder "docs". You need to install the requirements:
pip install -r docs/docs_requirements.txt
After editing, build the documentation locally by running
sphinx-build -b html ~/path/to/pvcompare/docs/ ~/path/to/pvcompare/pvcompare_docs/
to check the results by opening the html files in the directory pvcompare_docs
.
An introduction to creating the readthedocs with Sphinx is given here: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html.