diff --git a/general/setup.md b/general/setup.md index 91ad135..dfff002 100755 --- a/general/setup.md +++ b/general/setup.md @@ -20,6 +20,14 @@ Extensions and software marked with `*` are optional but recommended. They are o Steps which are not explained in this documentation are how to install and setup the above mentioned software and extensions. You also should configure the web server paths accordingly in order to access the application in the browser. +### IDE / Editor + +Which IDE or editor a developer uses is up to the individual developer. From experience the following opinionated choices provided good results: + +* Visual Studio Code (vscode) +* Sublime +* PHPStorm (mostly for php, html, css, js) + ### Installation Options 1. Option 1: Full installation, code checks/tests, generating documentation. **Not recomended as quick setup** @@ -87,12 +95,14 @@ This will only setup the application including some dummy data and also perform 5. Install Composer 6. Run `composer install` inside `Karaka` 7. Create the database table `oms` -7. Run `php demoSetup/setup.php` inside `Karaka` +8. Run `php demoSetup/setup.php` inside `Karaka` (takes a long time: > 1h) After the installation you'll have access to the following content: * Application: `http://127.0.0.1` +Instead of calling `php demoSetup/setup.php` which only uses a single thread you may also run `php demoSetup/setup.php -a 0` which will execute the install script in multiple threads leading to most likely 100% CPU and storage usage but therfore significantly reduce the execution time. + ### Annotation * During this process the database automatically gets dropped (if it exists) and re-created @@ -110,27 +120,9 @@ php -dxdebug.profiler_enable=1 -dxdebug.mode=develop,debug,profile -dxdebug.outp > This may use a lot of resources and storage space (≈15 GB of cachegrind data w/o trace data and ≈120 GB w/ trace data) -## Git Hooks (Linux only) - -The git hooks perform various checks and validations during the `commit` and warn the developer about invalid code or code style/guideline violations. - -For developers it is recommended to copy the contents of the `default.sh` file in the `Build` repository under `Hooks` to your `pre-commit` file in the `.git/hooks` directory. If the `pre-commit` file doesn't exist just create it. - -The same should be done with every module. Simply go to `.git/modules/**/hooks` and also add the content of the `default.sh` file to all `pre-commit` files. - -By doing this every commit will be inspected and either pass without warnings, pass with warnings or stop with errors. This will allow you to fix code before committing it. Be aware only changed files will be inspected. Also make sure all `pre-commit` have `+x` permissions. - ## Tools -The following tools are important to test the application and to ensure the code quality. The configurations and sample shell executions can be found in the `Build` directory. These tools are also downloaded during the setup process of the `buildProject.sh` script. - -* composer -* phploc -* phpunit -* phpcs -* phpmetrics -* documentor -* phpstan +Especially in order to ensure the code quality various tools are used. Check out the inspection guidelines for further details. ## cOMS diff --git a/quality/inspections.md b/quality/inspections.md index 77d167e..5ed52cd 100755 --- a/quality/inspections.md +++ b/quality/inspections.md @@ -81,7 +81,7 @@ php -dxdebug.remote_enable=1 -dxdebug.mode=coverage,develop vendor/bin/phpunit - #### Modules -Every module needs to have a `Admin` directory containing a class called `AdminTest.php` which is used for testing the installation, activation, deactivation, uninstall and remove of the module. Tests that install, update, remove etc. a module need to have a group called `admin`. After running the `AdminTest.php` test the final state of the module should be installed and active, only this way it's possible to further test the controller and models. A code coverage of at least 80% is mandatory for every module for integration. +Every module needs to have a `Admin` directory containing a class called `AdminTest.php` which is used for testing the installation, activation, deactivation, uninstall and remove of the module. Tests that install, update, remove etc. a module need to have a group called `admin`. After running the `AdminTest.php` test the final state of the module should be installed and active, only this way it's possible to further test the controller and models. A code coverage of at least 90% is mandatory for every module for integration. ### PHPStan @@ -103,7 +103,9 @@ Besides the code tests and static code analysis the code style is another very i php vendor/bin/phpcs ./ --standard="Build/Config/phpcs.xml" -s --report-junit=Build/test/junit_phpcs.xml ``` -### Git Hooks (Linux only) +### Custom scripts + +#### Git Hooks (Linux only) The git hooks perform various checks and validations during the `commit` and warn the developer about invalid code or code style/guideline violations. @@ -111,4 +113,37 @@ For developers it is recommended to copy the contents of the `default.sh` file i The same should be done with every module. Simply go to `.git/modules/**/hooks` and also add the content of the `default.sh` file to all `pre-commit` files. -By doing this every commit will be inspected and either pass without warnings, pass with warnings or stop with errors. This will allow you to fix code before committing it. Be aware only changed files will be inspected. Also make sure all `pre-commit` files have `+x` permissions. \ No newline at end of file +By doing this every commit will be inspected and either pass without warnings, pass with warnings or stop with errors. This will allow you to fix code before committing it. Be aware only changed files will be inspected. Also make sure all `pre-commit` files have `+x` permissions. + +#### Release Report + +The [TestReportGenerator](https://github.com/Karaka-Management/TestReportGenerator) generates a customer report which outputs various information regarding tests (unit, integration, static) and code quality. The primary purpose of this report generator is to aggregate the code inspections in a printable format that can be used for auditing purposes on the customer side. + +```sh +php TestReportGenerator/src/index.php \ + -b /home/oms \ + -l /home/oms/Build/Config/reportLang.php \ + -c /home/oms/tests/coverage.xml \ + -s /home/oms/Build/test/junit_phpcs.xml \ + -sj /home/oms/Build/test/junit_eslint.xml \ + -a /home/oms/Build/test/phpstan.json \ + -u /home/oms/Build/test/junit_php.xml \ + -d /home/oms/Build/test/ReportExternal \ + --version 1.0.0 +``` + +## Demo setup + +A good way to setup a demo application with mostly randomly generated user input data is the **demoSetup** script which can be found in the repository https://github.com/Karaka-Management/demoSetup. + +The following command will create a demo application: + +```sh +php demoSetup/setup.php +``` + +In some cases code changes may require changes to the demo setup script (e.g. changes in the api, new modules). Since the demo setup script tries to simulate user generated data it takes some time to run. You may speed up the runtime by parallelizing the execution. However, this may use up 100% of your CPU and storage performance. + +```sh +php demoSetup/setup.php -a 0 +```