Merge branch 'develop' of https://github.com/Karaka-Management/Developer-Guide into develop

general/first_steps.md

@@ -1,6 +1,6 @@
 # First steps
 
-After you installed the application and configured your development environment you are ready to make your first code contributions.
+After you [installed]({%}?page=general/setup.md) the application and configured your development environment you are ready to make your first code contributions.
 
 Please note that besides the general development guide the organization also provides various other organizational documents which help to understand the processes, development status and decisions made.
 
@@ -11,3 +11,62 @@ Please note that besides the general development guide the organization also pro
 * [Conflict of interest](https://github.com/Karaka-Management/Organization-Guide/blob/master/Policies%20%26%20Guidelines/Conflict%20of%20Interest%20Policy.md)
 * [Activity Policy](https://github.com/Karaka-Management/Organization-Guide/blob/master/Policies%20%26%20Guidelines/Organization%20Activity%20Policy.md)
 * [Organization Guidelines](https://github.com/Karaka-Management/Organization-Guide/blob/master/Policies%20%26%20Guidelines/Organization%20Guidelines.md)
+
+## First tasks
+
+### Unit tests & code coverage
+
+Implement tests to improve code coverage. Uncovered lines can be found in the coverage [overview](https://dev.jingga.app/src/Karaka/build/coverage/).
+
+### Documentation
+
+#### Test documentation
+
+All tests need to have the following docblocks:
+
+##### Class
+
+```php
+/**
+ * @testdox phpOMS\tests\Image\SkewTest: Image skew
+ * @internal
+ */
+```
+
+* @testdox Is a one-line test description which is included in a test report for customers. The **FQN is very important**, it must be present.
+
+##### Function
+
+```php
+/**
+ * @testdox A image can be automatically unskewed
+ * @group framework
+ * @covers phpOMS\Image\Skew
+ */
+```
+
+* @testdox Is a one-line test description which is included in a test report for customers.
+* @group Is mostly `framework` (for phpOMS) or `module` for (for Modules)
+* @covers Is used to restrict the class which is getting covered by this test
+
+#### Module documentation
+
+Modules have a `Help` and a `Dev` documentation both are insifficient for most modules. Feel free to add some documentation. Consider to use images wherever helpful. Consider to add the used images to https://github.com/Karaka-Management/Build/blob/master/Js/createImages.js which will automatically create new images even if the style changes or minor layout changes are made.
+
+```js
+...
+    [
+        'http://192.168.178.38/en/admin/module/settings?id=Admin#c-tab-3',
+        '//*[@id="content"]',
+        __dirname + '/../../Modules/Admin/Docs/Help/img/admin-module-admin-settings-design.png'
+    ],
+...
+```
+
+1. Url to the endpoint (must use the same IP used in other examples)
+2. XPath of the content you want to take an image from
+3. Output directory
+
+### Todos
+
+Usually todos with **low** priority and **easy** difficulty are good beginner todos: https://github.com/orgs/Karaka-Management/projects/10.

general/setup.md

@@ -70,6 +70,9 @@ Additional tools and settings coming with the VM:
 3. Trace visualization `http://vm_ip:81`
    1. Download the latest trace from `http://vm_ip:82/Logs`
    2. Drag and drop that downloaded `*.xt` file in the trace visualizer
+4. sitespeed.io `http://vm_ip:83`
+
+<img width="150px" src="./img/webgrind.jpg"> <img width="150px" src="./img/trace_visualizer.jpg"> <img width="150px" src="./img/sitespeed.jpg"> <img width="150px" src="./img/codecoverage.jpg"> <img width="150px" src="./img/coverage_analysis.jpg"> <img width="150px" src="./img/metrics.jpg">
 
 ### Option 2: Demo Application
 
@@ -139,3 +142,7 @@ After the installation you'll have access to the following content:
 If you are interest on working on the c++ code base you will in addition need the following tools and libraries:
 
 * [OpenCV](https://docs.opencv.org/3.4/d7/d9f/tutorial_linux_install.html)
+
+## References
+
+[Installation](https://github.com/Karaka-Management/User-Guide/blob/develop/setup/install.md)

quality/inspections.md

@@ -7,6 +7,8 @@ Code inspections are very important in order to maintain the same code quality t
 The following automated tests must pass without errors, failures and warnings for successful code changes:
 
 * `php ./vendor/bin/phpstan analyse -l 9 -c Build/Config/phpstan.neon ./`
+* `php vendor/bin/php-cs-fixer fix ./ --config=Build/Config/.php-cs-fixer.php --allow-risky=yes`
+* `php vendor/bin/phpcbf --standard=Build/Config/phpcs.xml ./`
 * `php ./vendor/bin/phpcs --severity=1 ./ --standard="Build/Config/phpcs.xml"`
 * `php ./vendor/bin/phpunit -c tests/phpunit_no_coverage.xml`
 * `php ./vendor/bin/rector process --config Build/Config/rector.php --dry-run ./`
@@ -15,6 +17,8 @@ The following automated tests must pass without errors, failures and warnings fo
 * `./cOMS/tests/test.sh`
 * see [other checks](#other-checks) below
 
+<img width="150px" src="./img/webgrind.jpg"> <img width="150px" src="./img/trace_visualizer.jpg"> <img width="150px" src="./img/sitespeed.jpg"> <img width="150px" src="./img/codecoverage.jpg"> <img width="150px" src="./img/coverage_analysis.jpg"> <img width="150px" src="./img/metrics.jpg"> <img width="150px" src="./img/phpunit_html.jpg"> <img width="150px" src="./img/phpcs.jpg"> <img width="150px" src="./img/phpstan.jpg"> <img width="150px" src="./img/rector.jpg">
+
 Alternatively you can simply run the helper script in the Build repository, which executes a few of the above mentioned checks:
 
 ```sh
@@ -121,11 +125,11 @@ Tools used for the code inspection are:
 * PHPStan
 * Jasmine
 * PHPCS
+* PHP CS Fixer
+* PHP CBF
 * Rector
 * Custom scripts/tools
 
-These tools are all installed by running the `setup.sh` script from the Build repository.
-
 ### PHPUnit
 
 This application uses PHPUnit as unit testing framework. Unit tests for specific classes need to be named in the same manner as the testing class.
@@ -176,6 +180,22 @@ php vendor/bin/phpcs --severity=1 ./ --standard="Build/Config/phpcs.xml" -s --re
 
 > Many IDEs allow to integrate phpcs rules/configuration files for automatic checks in the editor
 
+### PHP CS Fixer
+
+The php code base has a defined code style standard. The following command automatically fixes some of the violations
+
+```sh
+php vendor/bin/php-cs-fixer fix ./ --config=Build/Config/.php-cs-fixer.php --allow-risky=yes
+```
+
+### PHP CBF
+
+The php code base has a defined code style standard. The following command automatically fixes some of the violations
+
+```sh
+php vendor/bin/phpcbf --standard=Build/Config/phpcs.xml ./
+```
+
 ### Rector
 
 ```sh
@@ -200,6 +220,14 @@ npx eslint ./ -c Build/Config/.eslintrc.json
 
 > Many IDEs allow to integrate eslint rules/configuration files for automatic checks in the editor
 
+### Sitespeed
+
+You can perform sitespeed checks by using sitespeed.io. Example:
+
+```sh
+sitespeed.io http://192.168.178.38 -b chrome --outputFolder /var/www/html/sitespeed
+```
+
 ### Custom scripts
 
 #### C++ tests