|
2 | 2 | ## General steps
|
3 | 3 | Contributing to Kapowarr consists of 5 steps, listed hereunder.
|
4 | 4 |
|
5 |
| -1. Make a [contributing request](https://github.com/Casvt/Kapowarr/issues/new?template=contribute-request.md), where you describe what you plan on doing. This request needs to get approved before you can start, or your pull request won't be accepted. This is to avoid multiple people from doing the same thing and to avoid you wasting your time if we do not wish the changes. This is also where discussions can be held about how something will be implemented. |
6 |
| -2. When the request is accepted, start your local development (more info about this below). |
7 |
| -3. When done, create a pull request to the development branch, where you mention again what you've changed/added and give a link to the original contributing request issue. |
8 |
| -4. The PR will be reviewed and if requested, changes will need to be made before it is accepted. |
| 5 | +1. Make a [contributing request](https://github.com/Casvt/Kapowarr/issues/new?template=contribute_request.md), where you describe what you plan on doing. _This request needs to get approved before you can start._ The contributing request has multiple uses: |
| 6 | + 1. Avoid multiple people working on the same thing. |
| 7 | + 2. Avoid you wasting your time on changes that we do not wish for. |
| 8 | + 3. If needed, have discussions about how something will be implemented. |
| 9 | + 4. A place for contact, be it questions, status updates or something else. |
| 10 | +2. When the request is accepted, start your local development (more info on this below). |
| 11 | +3. When done, create a pull request to the development branch, where you quickly mention what has changed and give a link to the original contributing request issue. |
| 12 | +4. The PR will be reviewed. Changes might need to be made in order for it to be merged. |
9 | 13 | 5. When everything is okay, the PR will be accepted and you'll be done!
|
10 | 14 |
|
11 |
| -## Local development steps |
12 |
| -Once your request is accepted, you can start your local development. |
| 15 | +## Local development |
13 | 16 |
|
14 |
| -1. Clone the repository onto your computer and open it using your preferred IDE (Visual Studio Code is used by us). |
15 |
| -2. Make the changes needed and write accompanying tests if needed. |
16 |
| -3. Check if the code written follows the styling guide below. |
17 |
| -4. Run the finished version, using python 3.8, to check if you've made any errors. |
18 |
| -5. Run the tests (unittest is used). This can be done with a button click within VS Code, or with the following command where you need to be inside the root folder of the project: |
| 17 | +Once your contribution request has been accepted, you can start your local development. |
| 18 | + |
| 19 | +### IDE |
| 20 | + |
| 21 | +It's up to you how you make the changes, but we use Visual Studio Code as the IDE. A workspace settings file is included that takes care of some styling, testing and formatting of the backend code. |
| 22 | + |
| 23 | +1. The vs code extension `ms-python.vscode-pylance` in combination with the settings file with enable type checking. |
| 24 | +2. The vs code extension `ms-python.mypy-type-checker` in combination with the settings file will enable mypy checking. |
| 25 | +3. The vs code extension `ms-python.autopep8` in combination with the settings file will format code on save. |
| 26 | +4. The vs code extension `ms-python.isort` in combination with the settings file will sort the import statements on save. |
| 27 | +5. The settings file sets up the testing suite in VS Code such that you can just click the test button to run all tests. |
| 28 | + |
| 29 | +If you do not use VS Code with the mentioned extensions, then below are some commands that you can manually run in the base directory to achieve similar results. |
| 30 | + |
| 31 | +1. **Mypy**: |
| 32 | +```bash |
| 33 | +mypy --explicit-package-bases . |
| 34 | +``` |
| 35 | +2. **autopep8**: |
| 36 | +```bash |
| 37 | +autopep8 --recursive --in-place . |
| 38 | +``` |
| 39 | +3. **isort**: |
| 40 | +```bash |
| 41 | +isort . |
| 42 | +``` |
| 43 | +4. **unittest** |
19 | 44 | ```bash
|
20 | 45 | python3 -m unittest discover -s ./tests -p '*.py'
|
21 | 46 | ```
|
22 |
| -6. Test your version thoroughly to catch as many bugs as possible (if any). |
23 |
| - |
24 |
| -## Styling guide |
25 |
| -The code of Kapowarr is written in such way that it follows the following rules. Your code should too. |
26 |
| - |
27 |
| -1. Compatible with python 3.8 to 3.11 . |
28 |
| -2. Tabs (4 space size) are used for indentation. |
29 |
| -3. Use type hints as much as possible. If you encounter an import loop because something needs to be imported for type hinting, utilise [`typing.TYPE_CHECKING`](https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING). |
30 |
| -4. Each function in the backend needs a doc string describing the function, what the inputs are, what errors could be raised from within the function and what the output is. |
31 |
| -5. The imports need to be sorted (the extension `isort` is used in VS Code). |
32 |
| -6. The code needs to be compatible with Linux, MacOS, Windows and the Docker container. |
33 |
| -7. The code should, though not strictly enforced, reasonably comply with the rule of 80 characters per line. |
| 47 | + |
| 48 | +### Strict rules |
| 49 | + |
| 50 | +There are a few conditions that should always be met: |
| 51 | + |
| 52 | +1. Kapowarr should support Python version 3.8 and higher. |
| 53 | +2. Kapowarr should be compatible with Linux, MacOS, Windows and the Docker container. |
| 54 | +3. The tests should all pass. |
| 55 | + |
| 56 | +### Styling guide |
| 57 | + |
| 58 | +Following the styling guide for the backend code is not a strict rule, but effort should be put in to conform to it as much as possible. Running autopep8 and isort handles most of this. |
| 59 | + |
| 60 | +1. Indentation is done with 4 spaces. Not using tabs. |
| 61 | +2. Use type hints as much as possible. If you encounter an import loop because something needs to be imported for type hinting, utilise [`typing.TYPE_CHECKING`](https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING). |
| 62 | +3. A function in the backend needs a doc string describing the function, what the inputs are, what errors could be raised from within the function and what the output is. |
| 63 | +4. The imports need to be sorted. |
| 64 | +5. The code should, though not strictly enforced, reasonably comply with the rule of 80 characters per line. |
| 65 | + |
| 66 | +## A few miscellaneous notes |
| 67 | + |
| 68 | +1. Kapowarr does not have many tests. They're not really required if you checked your changes for bugs already. But you are free to add tests for your changes anyway. |
| 69 | +2. The function [`backend.base.file_extraction.extract_filename_data`](https://github.com/Casvt/Kapowarr/blob/eadc04d10b32c04d4bbc51d289d10cfa93bc44f6/backend/base/file_extraction.py#L186) and [the regexes defined at the top](https://github.com/Casvt/Kapowarr/blob/development/backend/base/file_extraction.py#L24-L55) that it uses have become a bit of a box of black magic. If the function does not work as expected, it might be best to just inform @Casvt in the contribution request issue and he'll try to fix it. |
0 commit comments