Merge pull request #149 from RAMP-project/joss-paper

Joss paper

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,19 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[Bug] Bug_short_description"
+labels: bug
+assignees: ''
+
+---
+
+Describe_the_bug
+
+Checklist to make sure that the bug report ist complete:
+- [ ] OS: *your_operating_system*, *your_distribution*
+- [ ] RAMP version or Branch: *RAMP version* or *branch_name*, updated on *update_date*
+- [ ] If applicable: Attach full error message
+- [ ] If applicable: Share screenshots/images of your problem
+- [ ] If applicable: Share used input data
+
+<sub>*For more information on how to contribute, please check the [Contributing Guidelines](https://github.com/RAMP-project/RAMP/blob/main/CONTRIBUTING.md).*<sub>

.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,16 @@
+---
+name: Custom issue template
+about: If your issue is not a bug
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+
+Providing the following information will help RAMP developers assisting you:
+- [ ] OS: *your_operating_system*, *your_distribution*
+- [ ] RAMP version or Branch: *RAMP version* or *branch_name*, updated on *update_date*
+- [ ] If applicable: Share used input data
+- 
+<sub>*For more information on how to contribute, please check the [Contributing Guidelines](https://github.com/RAMP-project/RAMP/blob/main/CONTRIBUTING.md).*<sub>

.github/pull_request_template.md

@@ -0,0 +1,6 @@
+Fix #Issue
+
+**Changes proposed in this pull request**:
+- Your_changes
+
+<sub>*For more information on how to contribute, please check the [Contributing Guidelines](https://github.com/RAMP-project/RAMP/blob/main/CONTRIBUTING.md).*<sub>

.github/workflows/pytest.yml

@@ -5,9 +5,9 @@ name: RAMP tests
 
 on:
   push:
-    branches: [ "main", "development" ]
+    branches: [ "main", "development", "joss-paper"]
   pull_request:
-    branches: [ "main", "development" ]
+    branches: [ "main", "development", "joss-paper"]
 
 permissions:
   contents: read
@@ -26,7 +26,7 @@ jobs:
     - name: Install black
       run: |
         python -m pip install --upgrade pip
-        pip install black
+        pip install black[jupyter]==24.4.2
     - name: Lint with black
       run: |
         black . --check
@@ -37,4 +37,15 @@ jobs:
         pip install -r tests/requirements.txt
     - name: Test with pytest
       run: |
-        pytest tests/
+        coverage run -m pytest tests/
+
+    - name: Check test coverage
+      run: |
+        coverage report -m
+
+    - name: Report to coveralls
+      run: |
+        coveralls
+      env:
+        COVERALLS_REPO_TOKEN: ${{ secrets.COVERALL_TOKEN }}
+        COVERALLS_SERVICE_NAME: github

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+exclude: '.git'
+default_stages: [commit]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+
+  - repo: https://github.com/psf/black
+    rev: 24.4.2
+    hooks:
+      - id: black

AUTHORS

@@ -23,3 +23,4 @@ Maria C.G. Hart, Leibniz Universität Hannover <[email protected]>
 Francesco Sanvito, TU Delft <[email protected]>
 Gregory Ireland, Reiner Lemoine Institut <[email protected]>
 Sergio Balderrama, Universidad Mayor de San Simon <[email protected]>
+Johann Kraft, Reiner Lemoine Institut <[email protected]>

CONTRIBUTING.md

@@ -13,16 +13,40 @@ Some of the resources to look at if you're interested in contributing:
 
 By contributing to RAMP, e.g. through opening a pull request or submitting a patch, you represent that your contributions are your own original work and that you have the right to license them, and you agree that your contributions are licensed under the EUROPEAN UNION PUBLIC LICENCE v. 1.2.
 
+## Open an issue
+
+[Open an issue](https://github.com/RAMP-project/RAMP/issues) to report a bug or for a feature request, please try to provide the information summarized below
+
+- OS: *your_operating_system*, *your_distribution*
+- RAMP version or Branch: *RAMP version* or *branch_name*, updated on *update_date*
+- If applicable: Attach full error message
+- If applicable: Share screenshots/images of your problem
+- If applicable: Share used input data
+
 ## Submitting changes
 
 To contribute changes:
 - Fork the project on GitHub
+- Follow the "Setup" steps below
 - Create a feature branch (e.g. named "add-this-new-feature") to work on in your fork
 - Add your name to the [AUTHORS](AUTHORS) file
 - Commit your changes to the feature branch
 - Push the branch to GitHub
 - On GitHub, create a new pull request from the feature branch
 
+### Setup
+
+1. Create a virtual environment and install the dev dependencies with
+
+        pip install -r dev_requirements.txt
+
+2. Install the pre-commit hooks with
+
+        pre-commit install
+
+   This will mainly make sure you can't commit if your code is not linted with black.
+   The pre-commit hook will check if your code is linted and if it is not it will simply lint it for you, you then only need to stage the changes made by the linter and commit again, as simple as that :)
+
 ### Pull requests
 
 Before submitting a pull request, check whether you have:
@@ -44,18 +68,32 @@ Please try to write clear commit messages. One-line messages are fine for small
 
 ## Testing
 
-We have a qualitative testing functionality that allows to compare the results arising from a modified version of the code against default ones, for the 3 reference input files provided within the code itself.
+Testing is used by RAMP developers to make sure their new feature/bug fix is not breaking existing code. As RAMP is stochastic some tests are only qualitative, other unit tests are ran by GitHub Actions.
+
+Before running the tests locally, you need to install the testing dependencies
+
+```
+pip install -r tests/requirements.txt
+```
+
+### Qualitative testing
+
+The qualitative testing functionality allows to compare the results arising from a modified version of the code against default ones, for the 3 reference input files provided within the code itself.
+
+To run the qualitative test, you'll have to run
+ ```
+ python ramp/test/test_run.py
+ ```
+from the root level of this repository.
+
+If you already ran this script, you will be asked if you want to overwrite the results files (if you decide not to, the results are not going to be regenerated from your latest code version). You should compare the results of your code and those saved from the latest stable version thanks to the image which is displayed after the script ran.
 
-This functionality is accessible via `test/test_run.py`. To run the qualitative test, you'll have to go through the following steps:
-   1. run your modified code for the 3 reference input files for 30 days each. This will create 3 corresponding output files in the `results` folder
-   2. run `test/test_run.py` and visualise the comparison between the results of your code and those obtainable with the latest stable version
-
 Ideally, the difference between reference and new results should be minimal and just due to the stochastic nature of the code. If more pronounced, it should be fully explainable based on the changes made to the code and aligned to the expectations of the developers (i.e. it should reflect a change in the output *wanted* and precisely *sought* with the commit in question).
 
 ### Unit tests
 
-Install `pytest` (`pip install pytest`) and run `pytest tests/` form the root of the repository to run the unit tests
+Run `pytest tests/` form the root of the repository to run the unit tests.
 
 ## Attribution
 
-The layout and content of this document is partially based on [calliope](https://github.com/calliope-project/calliope/blob/master/CONTRIBUTING.md)'s equivalent document.
+The layout and content of this document is partially based on [calliope](https://github.com/calliope-project/calliope/blob/master/CONTRIBUTING.md)'s equivalent document.

README.rst

@@ -11,6 +11,10 @@
     :target: https://rampdemand.readthedocs.io/en/latest/?badge=latest
     :alt: Documentation Status
 
+.. image:: https://coveralls.io/repos/github/RAMP-project/RAMP/badge.svg?branch=main
+:target: https://coveralls.io/github/RAMP-project/RAMP?branch=main
+
+
 .. image:: https://github.com/RAMP-project/RAMP/blob/main/docs/source/_static/RAMP_logo_basic.png?raw=true
    :width: 300
 
@@ -44,7 +48,7 @@ Installing through pip
 
 .. code-block:: python
 
-   conda create -n ramp python=3.8
+   conda create -n ramp python=3.10
 
 
 2. If you create a new environment for RAMP, you'll need to activate it each time before using it, by writing
@@ -189,12 +193,15 @@ Other options are documented in the help of `ramp`, which you access with the ``
    ramp -h
 
 
-If you have existing python input files, you can convert them to
-spreadsheet. To do so, go to the ``\ramp`` folder and run
+If you have existing python input files from RAMP version prior to 0.5, you can convert them to
+spreadsheets input files. Simply run
 
 .. code-block:: bash
 
-   python ramp_convert_old_input_files.py -i <path to the input file you wish to convert>
+   ramp_convert -i <path to the .py input file you wish to convert>
+
+If you want to save a RAMP model you created with a .py file into a spreadsheet refer to
+this `example <https://rampdemand.readthedocs.io/en/latest/examples/using_excel/using_excel.html#exporting-the-database>`_
 
 For other examples of command lines options, such as setting date ranges, please visit `the dedicated section  <https://rampdemand.readthedocs.io/en/latest/examples/year_simulation/year_simulation.html#setting-date-range>`_ of the documentation.
 
@@ -279,16 +286,7 @@ Contributing
 ============
 This project is open-source. Interested users are therefore invited to test, comment or contribute to the tool. Submitting issues is the best way to get in touch with the development team, which will address your comment, question, or development request in the best possible way. We are also looking for contributors to the main code, willing to contribute to its capabilities, computational-efficiency, formulation, etc.
 
-To contribute changes:
-
-#. Fork the project on GitHub
-#. Create a feature branch (e.g. named "add-this-new-feature") to work on in your fork
-#. Add your name to the `AUTHORS <https://github.com/RAMP-project/RAMP/blob/development/AUTHORS>`_ file
-#. Commit your changes to the feature branch
-#. Push the branch to GitHub
-#. On GitHub, create a new pull request from the feature branch
-
-When committing new changes, please also take care of checking code stability by means of the `qualitative testing <https://github.com/RAMP-project/RAMP/blob/development/CONTRIBUTING.md>`_ functionality.
+To contribute changes please consult our `Contribution guidelines <https://github.com/RAMP-project/RAMP/blob/main/CONTRIBUTING.md>`_
 
 
 How to cite

dev_requirements.txt

@@ -0,0 +1,3 @@
+pre-commit
+black==24.4.2
+-r tests/requirements.txt

docs/docs-requirements.txt

@@ -11,9 +11,7 @@ sphinx >= 1.6.4
 nbsphinx
 ipykernel
 sphinx-autobuild
-sphinx-pdj-theme # TODO to comment
 sphinx-copybutton
-sphinxjp.themes.sphinxjp
-sphinxjp.themes.basicstrap
+sphinx_wagtail_theme
 nbformat
 nbconvert