From d99893da917fbb173a0a8ffba212bb57b9f90f96 Mon Sep 17 00:00:00 2001 From: Spiros Maggioros Date: Tue, 9 Jul 2024 11:05:13 +0300 Subject: [PATCH 1/3] Documentation update regarding contributions and test cases --- .github/CONTRIBUTE/contribute.md | 69 ++++++++++++++++++++++++++++ .github/CONTRIBUTE/unit_tests.md | 36 +++++++++++++++ .github/ISSUE_TEMPLATE/bug_report.md | 12 ++--- 3 files changed, 111 insertions(+), 6 deletions(-) create mode 100644 .github/CONTRIBUTE/contribute.md create mode 100644 .github/CONTRIBUTE/unit_tests.md diff --git a/.github/CONTRIBUTE/contribute.md b/.github/CONTRIBUTE/contribute.md new file mode 100644 index 0000000..f934c84 --- /dev/null +++ b/.github/CONTRIBUTE/contribute.md @@ -0,0 +1,69 @@ +--- +name: Contribution guide +about: How to contribute +title: "[CONTRIBUTE] " +labels: '' +assignees: '' +--- + +### **How to contribute?** +* Open a pull request exaplaining your addition/fix. You can also see the [Bug report](../ISSUE_TEMPLATE/bug_report.md) + +* Implementation is not everything. You have to add test cases for every function that you add at the [tests](../../tests/) folder. + +* Last but not least, some documentation will be good for the users to learn how to use your code. You can add your documentation at the [docs](../../docs/) folder. + +### **Good practices** +* We have automated test cases that are located at the [tests](../../tests/) folder. The workflow will automatically run the test cases on your PR, but, before creating a PR make sure your test cases run correctly localy using this command ```cd tests/unit && python -m unittest discover -s . -p "*.py"``` + +* Make sure that you add any new libraries that you may use at [dev-dependencies](../../dev-dependencies.txt) as well as updating the [setup.py](../../setup.py) file(if needed). + +* Try to add docstrings on every new function that you implement as it will automatically be generated to documentation.Comments should look like this + - For functions: + ```python + def your_function(param1: type, param2: type, ...) -> return_type: + """ + Describe briefly what your function does + + Args: + param1(type): Describe what param1 is used for. + param2(type): Describe what param2 is used for. + etc. + Return: + return_type: Explain what your function returns. + """ + ``` + - For classes: + ```python + class your_class: + """ + Describe briefly what your class does + + Static attributes: + param1(type): Explain what param1 is used for. + param2(type): Explain what param2 is used for. + etc. + + Methods: + func1(param1, param2, ...): + Here you have to explain what func1 does using the tutorial above. + You have to do the same for every function. + + Note that you can add more docstrings inside function if you wish. + """ + def __init__(self, param1: type, param2: type, ...): + ... + + def func1(self, param1: type, param2: type, ...) -> return_type: + ... + ``` + +* As seen above, it is a good practice to always set parameter types in functions as well as return types. + +### **Useful files for contributions** + +* You can find all the csv samples at the [data](../../spare_scores/data/) folder. + +* You can find all the existing model weights at the [mdl](../../spare_scores/mdl/) folder. + +* All the code that is used for the documentation is located at the [contents](../../docs/source/) folder and you can manually add more. \ No newline at end of file diff --git a/.github/CONTRIBUTE/unit_tests.md b/.github/CONTRIBUTE/unit_tests.md new file mode 100644 index 0000000..7437c23 --- /dev/null +++ b/.github/CONTRIBUTE/unit_tests.md @@ -0,0 +1,36 @@ +--- +name: Unit testing guide +about: How to write unit tests +title: "[UNIT_TESTS] " +labels: '' +assignees: '' +--- + +### **How to write unit tests** +* As explained at the [contribution guide](contribute.md) it's a good practice to write test cases for any additions you make. For our test cases we use the unittest python3 library. The following is an example of a unit test with unittest library: + + ```python + + import unittest + + class CheckThisAndThat(unittest.TestCase): + + def testing_this(self): + self.data1 = ... + self.data2 = ... + # run your functions... + # result1 = my_func(self.data1, ...) + # result2 = my_func(self.data2, ...) + self.assertTrue(result1 == CorrectResult1) + self.assertTrue(result2 == CorrectResult2) + + def testing_that(self): + self.param1 = ... + self.param2 = ... + # run something + # model = my_model(self.param1, self.param2, ...) + # result1 = my_model.do_sth() + self.assertTrue(result1 == CorrectResult1) + ``` + + The following will run 2 test cases and 3 assertions. We explain how to run test cases at the [contribution guide](contribute.md). \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index b3b8c53..7ad501c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -7,25 +7,25 @@ assignees: '' --- -**Describe the bug** +### **Describe the bug** A clear and concise description of what the bug is. -**To Reproduce** +### **To Reproduce** Steps to reproduce the behavior: 1. Go to '...' 2. Click on '....' 3. Scroll down to '....' 4. See error -**Expected behavior** +### **Expected behavior** A clear and concise description of what you expected to happen. -**Screenshots** +### **Screenshots** If applicable, add screenshots to help explain your problem. -**Platform Info (please complete the following information):** +### **Platform Info (please complete the following information):** - OS: [e.g. Windows] + Version [e.g. 10] - spare_scores Version: 1.0.0 -**Additional context** +### **Additional context** Add any other context about the problem here. From 536e48ac4755814efb4ffb4cbdddd713f3fcb0c0 Mon Sep 17 00:00:00 2001 From: Spiros Maggioros Date: Tue, 9 Jul 2024 11:07:41 +0300 Subject: [PATCH 2/3] Small typo mistake --- .github/CONTRIBUTE/contribute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTE/contribute.md b/.github/CONTRIBUTE/contribute.md index f934c84..057a5a7 100644 --- a/.github/CONTRIBUTE/contribute.md +++ b/.github/CONTRIBUTE/contribute.md @@ -14,7 +14,7 @@ assignees: '' * Last but not least, some documentation will be good for the users to learn how to use your code. You can add your documentation at the [docs](../../docs/) folder. ### **Good practices** -* We have automated test cases that are located at the [tests](../../tests/) folder. The workflow will automatically run the test cases on your PR, but, before creating a PR make sure your test cases run correctly localy using this command ```cd tests/unit && python -m unittest discover -s . -p "*.py"``` +* We have automated test cases that are located at the [tests](../../tests/) folder. The workflow will automatically run the test cases on your PR, but, before creating a PR make sure your test cases run correctly locally using this command ```cd tests/unit && python -m unittest discover -s . -p "*.py"``` * Make sure that you add any new libraries that you may use at [dev-dependencies](../../dev-dependencies.txt) as well as updating the [setup.py](../../setup.py) file(if needed). From 2d0dfcbd66445f488db4b7d481a29bac84e55e09 Mon Sep 17 00:00:00 2001 From: Spiros Maggioros Date: Tue, 9 Jul 2024 11:20:54 +0300 Subject: [PATCH 3/3] Removed issue template matrix from new files --- .github/CONTRIBUTE/contribute.md | 8 -------- .github/CONTRIBUTE/unit_tests.md | 8 -------- 2 files changed, 16 deletions(-) diff --git a/.github/CONTRIBUTE/contribute.md b/.github/CONTRIBUTE/contribute.md index 057a5a7..0060871 100644 --- a/.github/CONTRIBUTE/contribute.md +++ b/.github/CONTRIBUTE/contribute.md @@ -1,11 +1,3 @@ ---- -name: Contribution guide -about: How to contribute -title: "[CONTRIBUTE] " -labels: '' -assignees: '' ---- - ### **How to contribute?** * Open a pull request exaplaining your addition/fix. You can also see the [Bug report](../ISSUE_TEMPLATE/bug_report.md) diff --git a/.github/CONTRIBUTE/unit_tests.md b/.github/CONTRIBUTE/unit_tests.md index 7437c23..ce5256c 100644 --- a/.github/CONTRIBUTE/unit_tests.md +++ b/.github/CONTRIBUTE/unit_tests.md @@ -1,11 +1,3 @@ ---- -name: Unit testing guide -about: How to write unit tests -title: "[UNIT_TESTS] " -labels: '' -assignees: '' ---- - ### **How to write unit tests** * As explained at the [contribution guide](contribute.md) it's a good practice to write test cases for any additions you make. For our test cases we use the unittest python3 library. The following is an example of a unit test with unittest library: