mirror of
https://github.com/Karaka-Management/Developer-Guide.git
synced 2026-01-11 12:28:41 +00:00
improve documentation
This commit is contained in:
parent
0a87e7259a
commit
d6d1a12f87
10
SUMMARY.md
10
SUMMARY.md
|
|
@ -1,17 +1,21 @@
|
|||
# General
|
||||
# Summary
|
||||
* [Introduction]({%}?page=README)
|
||||
* [Application Structure]({%}?page=general/structure)
|
||||
|
||||
## Setup
|
||||
* [Install]({%}?page=general/setup)
|
||||
* [First steps]({%}?page=general/first_steps)
|
||||
* [Application Structure]({%}?page=general/structure)
|
||||
|
||||
## Quality & Standards
|
||||
* [Code Inspections & Tests]({%}?page=quality/inspections)
|
||||
* [Documentation Standards]({%}?page=standards/documentation)
|
||||
* [General Code Standards]({%}?page=standards/general)
|
||||
* [Security Standards]({%}?page=security/security_guidelines)
|
||||
* [Html Coding Standards]({%}?page=standards/html)
|
||||
* [Php Coding Standards]({%}?page=standards/php)
|
||||
* [Js Coding Standards]({%}?page=standards/js)
|
||||
* [C++ Coding Standards]({%}?page=standards/cpp)
|
||||
* [Html Coding Standards]({%}?page=standards/html)
|
||||
* [Css Coding Standards]({%}?page=standards/css)
|
||||
|
||||
## Application Examples
|
||||
* [Application Sample]({%}?page=example_app/app)
|
||||
|
|
|
|||
|
|
@ -1,9 +0,0 @@
|
|||
# Contribution Guidelines
|
||||
|
||||
* Getting started
|
||||
* Permissions
|
||||
* Setup
|
||||
* Code style
|
||||
* Tests
|
||||
* Code of conduct
|
||||
* Code review
|
||||
12
general/first_steps.md
Normal file
12
general/first_steps.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# First steps
|
||||
|
||||
After you installed 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.
|
||||
|
||||
* [Development process](https://github.com/Karaka-Management/Docs/blob/master/Processes/Development.md)
|
||||
* [Project status](https://github.com/Karaka-Management/Docs/blob/master/Project/PROJECT.md)
|
||||
* [Code of conduct](https://github.com/Karaka-Management/Docs/blob/master/Policies%20%26%20Guidelines/Code%20of%20conduct.md)
|
||||
* [Conflict of interest](https://github.com/Karaka-Management/Docs/blob/master/Policies%20%26%20Guidelines/Conflict%20of%20Interest%20Policy.md)
|
||||
* [Activity Policy](https://github.com/Karaka-Management/Docs/blob/master/Policies%20%26%20Guidelines/Organization%20Activity%20Policy.md)
|
||||
* [Organization Guidelines](https://github.com/Karaka-Management/Docs/blob/master/Policies%20%26%20Guidelines/Organization%20Guidelines.md)
|
||||
174
general/setup.md
174
general/setup.md
|
|
@ -4,45 +4,97 @@ In order to setup the application for development for the first time please see
|
|||
|
||||
## Dev-Environment Requirements
|
||||
|
||||
Make sure your dev-environment or server fulfills the following requirements:
|
||||
Follow the general install/setup documentation until the application setup: [Install](https://github.com/Karaka-Management/Documentation/blob/develop/setup/install.md)
|
||||
|
||||
* PHP >= 8.0
|
||||
* PHP extensions: mbstring, gd, zip, dom, pdo, pdo-mysql/pdo-pgsql/pdo-sqlsrv, sqlite, bcmath, imap\*, redis\*, memcached\*, ftp\*, socket\*, curl\*, xml\*
|
||||
* Extension list: `php8.0 php8.0-dev php8.0-cli php8.0-common php8.0-mysql php8.0-pgsql php8.0-xdebug php8.0-opcache php8.0-pdo php8.0-sqlite php8.0-mbstring php8.0-curl php8.0-imap php8.0-bcmath php8.0-zip php8.0-dom php8.0-xml php8.0-phar php8.0-gd php-pear`
|
||||
* databases: mysql/postgresql/sqlsrv
|
||||
* web server: apache2/nginx
|
||||
* mod_headers (apache2)
|
||||
* software: tesseract-ocr\*, pdftotext\*, pdftoppm\*
|
||||
The following dev tools are highly recommended and the documentation assumes you installed them and added them to your environment paths on Windows. On linux they should be accessible immediately after installation.
|
||||
|
||||
The application and frameworks can use different databases. For the normal development process you only need one (whichever you prefer). However, in order to test against all supported databases and all code paths you would have to install all above mentioned databases.
|
||||
|
||||
Extensions and software marked with `*` are optional but recommended. They are only required in special situations. Requirements with a `/` in between mean that only one of the dependencies is necessary depending on your preferences and previous decisions.
|
||||
|
||||
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.
|
||||
* [git](https://git-scm.com/)
|
||||
* [composer](https://getcomposer.org/)
|
||||
* [npm](https://docs.npmjs.com/)
|
||||
|
||||
### 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)
|
||||
* [Visual Studio Code](https://code.visualstudio.com/)
|
||||
* [Sublime](https://www.sublimetext.com/)
|
||||
* [PhpStorm](https://www.jetbrains.com/phpstorm/) (mostly for php, html, css, js)
|
||||
|
||||
### Installation Options
|
||||
## Application install options
|
||||
|
||||
1. Option 1: Full installation, code checks/tests, generating documentation. **Not recomended as quick setup**
|
||||
2. Option 2: Only installs the application with some tests. Requires you to install the dev tools manually. **Recommended**
|
||||
3. Option 3: Only installs the application, due to the large amount of data takes some time to execute. **Recommended**
|
||||
1. Option: Only installs the application, due to the large amount of data takes some time to execute. **Recommended**
|
||||
2. Option: Only installs the application with some tests. Requires you to install the dev tools in advance. **Recommended**
|
||||
3. Option: Full installation, code checks/tests, generating documentation. **Not recomended**
|
||||
|
||||
## Option 1: Linux Shell Script
|
||||
### Option 1: Demo Application
|
||||
|
||||
This will only setup the application including some dummy data and also perform the code tests but no quality checks. Compared to option 2 this includes much more test data and it doesn't execute a unit test.
|
||||
|
||||
1. Go to the directory where you want to install the application
|
||||
2. Run `git clone -b develop https://github.com/karaka-management/Karaka.git`
|
||||
3. Run `git submodule update --init --recursive`
|
||||
4. Run `git submodule foreach git checkout develop`
|
||||
5. Run `composer install` inside `Karaka`
|
||||
6. Run `npm install` inside `Karaka`
|
||||
7. Create the database `oms` in your database management software
|
||||
8. Adjust the `demoSetup/config.php` file according to your settings (e.g. database user name + password)
|
||||
9. 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
|
||||
* The total storage space needed for this installation (w/o profiling data) is ≈10 GB
|
||||
* The database space needed for this installation is ≈500 MB
|
||||
* The runtime of the script is approx. 1h but can be slower depending on the hardware (slower CPU, hard drive vs SSD)
|
||||
|
||||
#### Profiling
|
||||
|
||||
You maybe want to use the following command to run the install script instead in order to also generate a cachegrind output for memory and performance profiling:
|
||||
|
||||
```sh
|
||||
php -dxdebug.profiler_enable=1 -dxdebug.mode=develop,debug,profile -dxdebug.output_dir=/your/path demoSetup/setup.php
|
||||
```
|
||||
|
||||
> 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)
|
||||
|
||||
### Option 2: PHPUnit Test Suits
|
||||
|
||||
This will only setup the application including some dummy data and also perform the code tests but no quality checks.
|
||||
|
||||
#### Steps
|
||||
|
||||
1. Go to the directory where you want to install the application
|
||||
2. Run `git clone -b develop https://github.com/karaka-management/Karaka.git`
|
||||
3. Run `git submodule update --init --recursive`
|
||||
4. Run `git submodule foreach git checkout develop`
|
||||
5. Run `composer install` inside `Karaka`
|
||||
6. Run `npm install` inside `Karaka`
|
||||
7. Create the database `oms` in your database management software
|
||||
8. Adjust the `tests/Bootstrap.php` file according to your settings (e.g. database user name + password)
|
||||
9. Run `php vendor/bin/phpunit --configuration tests/phpunit_no_coverage.xml` inside `Karaka` or open `http://127.0.0.1/Install`
|
||||
|
||||
After the installation you'll have access to the following content:
|
||||
|
||||
* Application: `http://127.0.0.1`
|
||||
* Code Coverager: `http://127.0.0.1/Build/coverage/`
|
||||
|
||||
> During this process the database automatically gets dropped (if it exists) and re-created. If you don't have `xdebug` installed but `phpdbg` you can replace `php phpunit ...` with `phpdbg -qrr phpunit.phar ...` or use `pcov` for much faster code coverage generation.
|
||||
|
||||
### Option 3: Linux Shell Script
|
||||
|
||||
This also installs all required dev tools and sets up the directory structure by itself. Using this method also tears down previous installs for a fresh install perfect for re-installing from the current development version. Furthermore, the use of PHPUnit also makes sure that the application is working as intended. The PHPUnit install also provides lots of dummy data for better integration and functionality testing of your own code/modules.
|
||||
|
||||
### Steps
|
||||
#### Steps
|
||||
|
||||
The following steps will setup the application, download all necessary tools and perform extensive code quality checks and documentation tasks:
|
||||
|
||||
1. Go to the directory where you want to install the build script
|
||||
1. Go to the directory where you want to install the build script (this is not the place where you want to install the application)
|
||||
2. Run `git clone -b develop https://github.com/karaka-management/Build.git`
|
||||
3. Modify `config.sh` (most likely the db credentials and paths)
|
||||
4. Run `chmod +x buildProject.sh`
|
||||
|
|
@ -57,76 +109,12 @@ After the installation you'll have access to the following content:
|
|||
* PHPStan Report: `${INSPECTION_PATH}/test/phpstan.json`
|
||||
* ... and more
|
||||
|
||||
### Annotation
|
||||
|
||||
During this process the database automatically gets dropped (if it exists) and re-created. If you don't have `xdebug` installed but `phpdbg` you can replace `php phpunit ...` with `phpdbg -qrr phpunit.phar ...` or use `pcov` for much faster code coverage generation in `Build/Inspection/Php/tests.sh`
|
||||
|
||||
## Option 2: PHPUnit Test Suits
|
||||
|
||||
This will only setup the application including some dummy data and also perform the code tests but no quality checks.
|
||||
|
||||
### Steps
|
||||
|
||||
1. Go to the directory where you want to install the application
|
||||
2. Run `git clone -b develop https://github.com/karaka-management/Karaka.git`
|
||||
3. Run `git submodule update --init --recursive`
|
||||
4. Run `git submodule foreach git checkout develop`
|
||||
5. Install Composer
|
||||
6. Run `composer install` inside `Karaka`
|
||||
7. Run `php vendor/bin/phpunit --configuration tests/phpunit_no_coverage.xml` inside `Karaka` or open `http://127.0.0.1/Install`
|
||||
|
||||
After the installation you'll have access to the following content:
|
||||
|
||||
* Application: `http://127.0.0.1`
|
||||
* Code Coverager: `http://127.0.0.1/Build/coverage/`
|
||||
|
||||
### Annotation
|
||||
|
||||
During this process the database automatically gets dropped (if it exists) and re-created. If you don't have `xdebug` installed but `phpdbg` you can replace `php phpunit ...` with `phpdbg -qrr phpunit.phar ...` or use `pcov` for much faster code coverage generation.
|
||||
|
||||
## Option 3: Demo Application
|
||||
|
||||
This will only setup the application including some dummy data and also perform the code tests but no quality checks. Compared to option 2 this includes much more test data and it doesn't execute a unit test.
|
||||
|
||||
1. Go to the directory where you want to install the application
|
||||
2. Run `git clone -b develop https://github.com/karaka-management/Karaka.git`
|
||||
3. Run `git submodule update --init --recursive`
|
||||
4. Run `git submodule foreach git checkout develop`
|
||||
5. Install Composer
|
||||
6. Run `composer install` inside `Karaka`
|
||||
7. Create the database table `oms`
|
||||
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
|
||||
* The total storage space needed for this installation (w/o profiling data) is ≈10 GB
|
||||
* The database space needed for this installation is ≈500 MB
|
||||
* The runtime of the script is approx. 1h but can be slower depending on the hardware (slower CPU, hard drive vs SSD)
|
||||
|
||||
### Profiling
|
||||
|
||||
You maybe want to use the following command to run the install script instead in order to also generate a cachegrind output for memory and performance profiling:
|
||||
|
||||
```sh
|
||||
php -dxdebug.profiler_enable=1 -dxdebug.mode=develop,debug,profile -dxdebug.output_dir=/your/path demoSetup/setup.php
|
||||
```
|
||||
|
||||
> 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)
|
||||
|
||||
## Tools
|
||||
|
||||
Especially in order to ensure the code quality various tools are used. Check out the inspection guidelines for further details.
|
||||
|
||||
> During this process the database automatically gets dropped (if it exists) and re-created. If you don't have `xdebug` installed but `phpdbg` you can replace `php phpunit ...` with `phpdbg -qrr phpunit.phar ...` or use `pcov` for much faster code coverage generation in `Build/Inspection/Php/tests.sh`
|
||||
>
|
||||
## cOMS
|
||||
|
||||
### OpenCV
|
||||
|
||||
https://docs.opencv.org/3.4/d7/d9f/tutorial_linux_install.html
|
||||
If you are interest on working on the c++ code base you will in addition need the following tools and libraries:
|
||||
|
||||
* [gcc](https://gcc.gnu.org/) version 7.5.0 or newer
|
||||
* [cmake](https://cmake.org/)
|
||||
* [OpenCV](https://docs.opencv.org/3.4/d7/d9f/tutorial_linux_install.html)
|
||||
|
|
|
|||
|
|
@ -91,18 +91,30 @@ With phpstan the code base is statically analyzed based on its configuration. Th
|
|||
php vendor/bin/phpstan analyse --autoload-file=phpOMS/Autoloader.php -l 8 -c Build/Config/phpstan.neon --error-format=prettyJson ./ > Build/test/phpstan.json
|
||||
```
|
||||
|
||||
### Jasmine
|
||||
|
||||
The javascript testing is done with jasmine. The javascript testing directory is structured the same way as the `Framework`. Unit tests for specific classes need to be named in the same manner as the testing class.
|
||||
|
||||
### PHP CS
|
||||
|
||||
Besides the code tests and static code analysis the code style is another very important inspection to ensure the code quality.
|
||||
The php code base has a defined code style standard. The easiest way to check for most rules is to run phpcs.
|
||||
|
||||
```sh
|
||||
php vendor/bin/phpcs ./ --standard="Build/Config/phpcs.xml" -s --report-junit=Build/test/junit_phpcs.xml
|
||||
```
|
||||
|
||||
> Many IDEs allow to integrate phpcs rules/configuration files for automatic checks in the editor
|
||||
|
||||
### Jasmine
|
||||
|
||||
The javascript testing is done with jasmine. The javascript testing directory is structured the same way as the `Framework`. Unit tests for specific classes need to be named in the same manner as the testing class.
|
||||
|
||||
### JS Eslint
|
||||
|
||||
The js code base has a defined code style standard. The easiest way to check for most rules is to run eslint.
|
||||
|
||||
```sh
|
||||
npx eslint jsOMS/ -c Build/Config/.eslintrc.json
|
||||
```
|
||||
|
||||
> Many IDEs allow to integrate eslint rules/configuration files for automatic checks in the editor
|
||||
|
||||
### Custom scripts
|
||||
|
||||
#### Git Hooks (Linux only)
|
||||
|
|
|
|||
15
standards/cpp.md
Normal file
15
standards/cpp.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
# C++
|
||||
|
||||
The c++ code should focus on using simplicity over "modern solutions". This may often mean to restrict the code on earlier c++ versions and sometimes even c code.
|
||||
|
||||
## Operating system support
|
||||
|
||||
C++ solutions must be valid on Windows 10 and Linux.
|
||||
|
||||
## Use of namespace
|
||||
|
||||
Namespaces must never be globally used. This means for example `use namespace std;` is prohibited and functions from the standard namespace should be prefixed instead `std::`
|
||||
|
||||
## Templates
|
||||
|
||||
Don't use c++ templates.
|
||||
10
standards/css.md
Normal file
10
standards/css.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
# Css
|
||||
|
||||
## Scss
|
||||
|
||||
Styles should be written in scss and transpiled to css.
|
||||
|
||||
## Browser support
|
||||
|
||||
Scss/css solutions must be valid on the newest versions of Edge, Firefox, Chrome and Safari.
|
||||
|
||||
|
|
@ -10,13 +10,25 @@ The phrase "side effects" means execution of logic not directly related to decla
|
|||
|
||||
"Side effects" include but are not limited to: generating output, explicit use of require or include, connecting to external services, modifying ini settings, emitting errors or exceptions, modifying global or static variables, reading from or writing to a file, and so on.
|
||||
|
||||
## Array
|
||||
## Character Encoding
|
||||
|
||||
Arrays should always bet initialized by using `[]`.
|
||||
PHP code MUST use only UTF-8 without BOM
|
||||
|
||||
```php
|
||||
$arr = [1, 2, 3];
|
||||
```
|
||||
## Line Ending
|
||||
|
||||
Lines MUST end with `\n` (LF) and MUST NOT have a whitespace at the end.
|
||||
|
||||
## File Ending
|
||||
|
||||
Files must end with a new line element `\n`.
|
||||
|
||||
## Member variables
|
||||
|
||||
Member variables should be public unless there is absolutely no reason directly access them or additional data manipulation upon setting, changing or returning them is required.
|
||||
|
||||
### Getters/Setters
|
||||
|
||||
Getters and setters for member variables should be kept at a minimum and only used when they actually perform additional actions, such as additional type checks, data manipulation, ...
|
||||
|
||||
## Indention
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,10 @@
|
|||
# Js
|
||||
|
||||
No deprecated or removed elements, functions or practices are allowed.
|
||||
The js code needs to be ECMAScript2021 compliant. No js ECMAScript2021 deprecated or removed elements, functions or practices are allowed. Please use the `.eslintrc` configuration for Eslint to identify most of the basic code standards.
|
||||
|
||||
## Browser support
|
||||
|
||||
Js solutions must be valid on the newest versions of Edge, Firefox, Chrome and Safari.
|
||||
|
||||
## Variable scope
|
||||
|
||||
|
|
@ -8,4 +12,12 @@ Variables should be defined with the scope in mind. `const` and `let` are the pr
|
|||
|
||||
## Deprecated functions and variables
|
||||
|
||||
* `eval`
|
||||
* `eval`
|
||||
|
||||
## Array
|
||||
|
||||
Arrays should always bet initialized by using `[]`.
|
||||
|
||||
```js
|
||||
arr = [1, 2, 3];
|
||||
```
|
||||
|
|
@ -1,23 +1,11 @@
|
|||
# Php
|
||||
|
||||
The php code needs to be php 7.4 compliant. No php 7.4 deprecated or removed elements, functions or practices are allowed (e.g. short open tag). Please use the `phpcs.xml` and `phpmd.xml` configurations for PHP Code Sniffer and PHP Mess Detector provided with the project to identify most of the basic code standards.
|
||||
The php code needs to be php 8.0 compliant. No php 8.0 deprecated or removed elements, functions or practices are allowed (e.g. short open tag). Please use the `phpcs.xml` configuration for PHP Code Sniffer to identify most of the basic code standards.
|
||||
|
||||
## Php Tags
|
||||
|
||||
PHP code MUST use the long `<?php ?>` tags or the short-echo `<?= ?>` tags; it MUST NOT use the other tag variations.
|
||||
|
||||
## Character Encoding
|
||||
|
||||
PHP code MUST use only UTF-8 without BOM
|
||||
|
||||
## Line Ending
|
||||
|
||||
Lines MUST end with `\n` (LF) and MUST NOT have a whitespace at the end.
|
||||
|
||||
## File Ending
|
||||
|
||||
Files must end with a new line element `\n`.
|
||||
|
||||
## Namespace and Class Names
|
||||
|
||||
Namespaces and classes MUST follow an "autoloading" PSR: [PSR-0, PSR-4].
|
||||
|
|
@ -106,6 +94,14 @@ Class constants MUST have a access modifier
|
|||
public CONST_NAME = ...;
|
||||
```
|
||||
|
||||
## Array
|
||||
|
||||
Arrays should always bet initialized by using `[]`.
|
||||
|
||||
```php
|
||||
$arr = [1, 2, 3];
|
||||
```
|
||||
|
||||
## Preferred Functions
|
||||
|
||||
### file_exists
|
||||
|
|
@ -116,14 +112,6 @@ Instead of using `\file_exists()` the functions `\is_dir()` or `\is_file()` shou
|
|||
|
||||
Don't use the internal enum implementations of PHP (neither `SplEnum` nor `enum`)
|
||||
|
||||
## Member variables
|
||||
|
||||
Member variables should be public unless there is absolutely no reason directly access them or additional data manipulation upon setting, changing or returning them is required.
|
||||
|
||||
### Getters/Setters
|
||||
|
||||
Getters and setters for member variables should be kept at a minimum and only used when they actually perform additional actions, such as additional type checks, data manipulation, ...
|
||||
|
||||
#### Model IDs
|
||||
|
||||
Model IDs must always be private. They must not have a setter. Therfore most models need/should have a getter function which returns the model ID.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user