Update docs
Michael Weimann
5 years ago
committed by
Igor Scheller
parent
f78e8c50bf
commit
d6ff7b5816
@ -1,10 +1,11 @@
|
|||||||
# Contributing
|
# Contributing
|
||||||
|
## Coding guide lines
|
||||||
## Code style
|
* Make sure you code follows the [PSR-12](https://www.php-fig.org/psr/psr-12/) code style.
|
||||||
|
|
||||||
* Make sure your code follows the [PSR-12](https://www.php-fig.org/psr/psr-12/) code style.
|
|
||||||
You may use `composer run phpcs` to verify that.
|
You may use `composer run phpcs` to verify that.
|
||||||
* Use `use` statements wherever possible instead of writing the fully qualified name.
|
* Use `use` statements wherever possible instead of writing the fully qualified name.
|
||||||
* Order the composer/npm dependencies alphabetically.
|
* Order the composer/npm dependencies alphabetically.
|
||||||
* Do not use code from the [includes](./includes) directory anywhere else.
|
* Do not use code from the [includes](./includes) directory anywhere else.
|
||||||
* If possible cover your code by test cases.
|
* Please cover your code by unit tests. Code under `includes` does not require tests.
|
||||||
|
|
||||||
|
## Pull requests
|
||||||
|
Please create single pull requests for every feature instead of creating one big monster of pull request containing a complete rewrite.
|
||||||
|
|||||||
@ -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.
|
||||||
Loading…
Reference in New Issue