diff --git a/general/first_steps.md b/general/first_steps.md index 34ca1bd..004fd07 100755 --- a/general/first_steps.md +++ b/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. diff --git a/general/img/codecoverage.jpg b/general/img/codecoverage.jpg new file mode 100644 index 0000000..8e21494 Binary files /dev/null and b/general/img/codecoverage.jpg differ diff --git a/general/img/coverage_analysis.jpg b/general/img/coverage_analysis.jpg new file mode 100644 index 0000000..894999e Binary files /dev/null and b/general/img/coverage_analysis.jpg differ diff --git a/general/img/metrics.jpg b/general/img/metrics.jpg new file mode 100644 index 0000000..0d6bf03 Binary files /dev/null and b/general/img/metrics.jpg differ diff --git a/general/img/sitespeed.jpg b/general/img/sitespeed.jpg new file mode 100644 index 0000000..db9e002 Binary files /dev/null and b/general/img/sitespeed.jpg differ diff --git a/general/img/trace_visualizer.jpg b/general/img/trace_visualizer.jpg new file mode 100644 index 0000000..c82d645 Binary files /dev/null and b/general/img/trace_visualizer.jpg differ diff --git a/general/img/webgrind.jpg b/general/img/webgrind.jpg new file mode 100644 index 0000000..b915778 Binary files /dev/null and b/general/img/webgrind.jpg differ diff --git a/general/setup.md b/general/setup.md index 9d94773..eee6381 100755 --- a/general/setup.md +++ b/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` + + ### 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) diff --git a/quality/img/codecoverage.jpg b/quality/img/codecoverage.jpg new file mode 100644 index 0000000..dba837f Binary files /dev/null and b/quality/img/codecoverage.jpg differ diff --git a/quality/img/coverage_analysis.jpg b/quality/img/coverage_analysis.jpg new file mode 100644 index 0000000..4c983a5 Binary files /dev/null and b/quality/img/coverage_analysis.jpg differ diff --git a/quality/img/metrics.jpg b/quality/img/metrics.jpg new file mode 100644 index 0000000..e0d339b Binary files /dev/null and b/quality/img/metrics.jpg differ diff --git a/quality/img/phpcs.jpg b/quality/img/phpcs.jpg new file mode 100644 index 0000000..003bc1e Binary files /dev/null and b/quality/img/phpcs.jpg differ diff --git a/quality/img/phpstan.jpg b/quality/img/phpstan.jpg new file mode 100644 index 0000000..fec9ee5 Binary files /dev/null and b/quality/img/phpstan.jpg differ diff --git a/quality/img/phpunit_html.jpg b/quality/img/phpunit_html.jpg new file mode 100644 index 0000000..6314fca Binary files /dev/null and b/quality/img/phpunit_html.jpg differ diff --git a/quality/img/rector.jpg b/quality/img/rector.jpg new file mode 100644 index 0000000..70ae535 Binary files /dev/null and b/quality/img/rector.jpg differ diff --git a/quality/img/sitespeed.jpg b/quality/img/sitespeed.jpg new file mode 100644 index 0000000..fb65921 Binary files /dev/null and b/quality/img/sitespeed.jpg differ diff --git a/quality/img/trace_visualizer.jpg b/quality/img/trace_visualizer.jpg new file mode 100644 index 0000000..4a5a4c8 Binary files /dev/null and b/quality/img/trace_visualizer.jpg differ diff --git a/quality/img/webgrind.jpg b/quality/img/webgrind.jpg new file mode 100644 index 0000000..02e9c17 Binary files /dev/null and b/quality/img/webgrind.jpg differ diff --git a/quality/inspections.md b/quality/inspections.md index ece1c9d..abe21dc 100755 --- a/quality/inspections.md +++ b/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 + + 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