From d6ff7b58161d80959a0880f0ddb37e3cf5ee91a0 Mon Sep 17 00:00:00 2001
From: Michael Weimann <mail@michael-weimann.eu>
Date: Fri, 17 Jan 2020 14:58:42 +0100
Subject: Update docs

---
 DEVELOPMENT.md | 130 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 DEVELOPMENT.md

(limited to 'DEVELOPMENT.md')

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 00000000..8f6e17a6
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,130 @@
+# Development
+
+Please also read the [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Dev requirements
+ * Node >= 8 (Development/Building only)
+   * Including npm
+ * Yarn (Development/Building only)
+ * PHP Composer (Development/Building only)
+
+## Local build
+The following instructions explain how to get, build and run the latest Engelsystem version directly from the git master branch (may be unstable!).
+
+ * Clone the master branch: `git clone https://github.com/engelsystem/engelsystem.git`
+ * Install [Composer](https://getcomposer.org/download/) and [Yarn](https://yarnpkg.com/en/docs/install) (which requires [Node.js](https://nodejs.org/en/download/package-manager/))
+ * Install project dependencies:
+     ```bash
+     composer install
+     yarn
+     ```
+    On production systems it is recommended to use
+    ```bash
+    composer install --no-dev
+    composer dump-autoload --optimize
+    ```
+    to install the Engelsystem
+ * Build the frontend assets
+    ```bash
+    yarn build
+    ```
+ * Optionally (for better performance)
+   * Generate translation files
+      ```bash
+      find resources/lang/ -type f -name '*.po' -exec sh -c 'file="{}"; msgfmt "${file%.*}.po" -o "${file%.*}.mo"' \;
+      ```
+
+## Testing
+To run the unit tests use
+```bash
+vendor/bin/phpunit --testsuite Unit
+``` 
+
+If a database is configured and the Engelsystem is allowed to mess around with some files, you can run feature tests.
+The tests can potentially delete some database entries, so they should never be run on a production system!
+```bash
+vendor/bin/phpunit --testsuite Feature
+# or for unit- and feature tests:
+vendor/bin/phpunit
+``` 
+
+To run code coverage reports its highly recommended to use [`pcov`](https://github.com/krakjoe/pcov) or
+at least `phpdbg -qrr`(which has problems with switch case statements) as using Xdebug slows down execution.
+```bash
+php -d pcov.enabled=1 vendor/bin/phpunit --testsuite Unit --coverage-text
+```
+
+## Translation
+We use gettext. You may use POEdit to extract new texts from the sourcecode.
+Please config POEdit to extract also the twig template files using the following settings: https://gist.github.com/jlambe/a868d9b63d70902a12254ce47069d0e6
+
+## Code style
+Please ensure that your pull requests follow the [PSR-12](https://www.php-fig.org/psr/psr-12/) coding style guide.
+You can check that by running
+```bash
+composer run phpcs
+```
+You may auto fix reported issues by running
+```bash
+composer run phpcbf
+```
+
+## CI & Build Pipeline
+
+The Engelsystem can be tested and automatically deployed to a testing/staging/production environment.
+This functionality requires a [GitLab](https://about.gitlab.com/) server with a working docker runner.
+
+To use the deployment features the following secret variables need to be defined (if undefined the step will be skipped):
+```bash
+SSH_PRIVATE_KEY         # The ssh private key
+STAGING_REMOTE          # The staging server, e.g. user@remote.host
+STAGING_REMOTE_PATH     # The path on the remote server, e.g. /var/www/engelsystem
+PRODUCTION_REMOTE       # Same as STAGING_REMOTE but for the production environment
+PRODUCTION_REMOTE_PATH  # Same as STAGING_REMOTE_PATH but for the production environment
+```
+
+## Docker
+
+This repo [ships a docker setup](docker/dev) for a quick development start.
+
+If you use another uid/gid than 1000 on your machine you have to adjust it in [docker/dev/.env](docker/dev/.env).
+
+Run this once
+
+```bash
+cd docker/dev
+docker-compose up
+```
+
+Run these commands once initially and then as required after changes
+
+```bash
+# Install composer dependencies
+docker exec -it engelsystem_dev_es_workspace_1 composer i
+
+# Install node packages
+docker exec -it engelsystem_dev_es_workspace_1 yarn install
+
+# Run a front-end build
+docker exec -it engelsystem_dev_es_workspace_1 yarn build
+
+# Update the translation files
+docker exec -it engelsystem_dev_es_workspace_1 find /var/www/resources/lang -type f -name '*.po' -exec sh -c 'file="{}"; msgfmt "${file%.*}.po" -o "${file%.*}.mo"' \;
+
+# Run the migrations
+docker exec -it engelsystem_dev_es_workspace_1 bin/migrate
+```
+
+While developing you may use the watch mode to rebuild the system on changes
+
+```bash
+# Run a front-end build
+docker exec -it engelsystem_dev_es_workspace_1 yarn build:watch
+```
+
+**Hint for using Xdebug with *PhpStorm***
+
+For some reason *PhpStorm* is unable to detect the server name.
+But without a server name it's impossible to set up path mappings.
+Because of that the docker setup sets the server name *engelsystem*.
+To get Xdebug working you have to create a server with the name *engelsystem* manually.
-- 
cgit v1.2.3-54-g00ecf