From 47992dee89bc22bf20aecd0d1f7b18f335889d95 Mon Sep 17 00:00:00 2001 From: Kevin Frantz Date: Sat, 19 Jan 2019 12:54:46 +0100 Subject: [PATCH] Optimized documentation --- DOCUMENTATION_CONVENTION.md | 6 ++- README.md | 2 +- administration/README.md | 2 +- application/README.md | 75 +++++++++++++++++++++++++++++++++++ application/symfony/README.md | 39 +++++++++++------- 5 files changed, 105 insertions(+), 19 deletions(-) create mode 100644 application/README.md diff --git a/DOCUMENTATION_CONVENTION.md b/DOCUMENTATION_CONVENTION.md index 6c0c2c3..549e4cf 100644 --- a/DOCUMENTATION_CONVENTION.md +++ b/DOCUMENTATION_CONVENTION.md @@ -1,7 +1,9 @@ -# Documentation -## convention +# Documentation Convention + +## Key Words The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the README.md files and in the comments of the code are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + ## README.md Each folder SHOULD contain a README.md file, which describes the domain of the folder. diff --git a/README.md b/README.md index 920833e..83495b8 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ To contributions of this project the "Contributor Covenant Code of Conduct" appl Further information you will find in the [administration README.md](./administration/README.md). ## Application -Further information you will find in the [application README.md](./application/README.md). +Further information about the application and the architecture you will find in the [application README.md](./application/README.md). ## Documentation Convention Further information you will find in the [DOCUMENTATION.md](./DOCUMENTATION_CONVENTION.md). diff --git a/administration/README.md b/administration/README.md index 5cc89bf..d4e59a1 100644 --- a/administration/README.md +++ b/administration/README.md @@ -42,7 +42,7 @@ This script copies the ***.env.dist*** files to the right locations. This script formats the PHP code with [PHP-CS-Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer). ### [generate-coverage-report.sh](./generate-coverage-report.sh.sh) -This script generates a coverage report with PHPUnit [PHPUnit](https://phpunit.de/). +This script generates a coverage report with [PHPUnit](https://phpunit.de/). ### [init.sh](./init.sh) diff --git a/application/README.md b/application/README.md new file mode 100644 index 0000000..42b858b --- /dev/null +++ b/application/README.md @@ -0,0 +1,75 @@ +## Application +## Architecture + +### Design Principles +The software MUST follow this design principles: + +#### [Domain Driven Design](https://de.wikipedia.org/wiki/Domain-driven_Design) +The software MUST use a DDD architecture. + +#### [SOLID](https://de.wikipedia.org/wiki/Prinzipien_objektorientierten_Designs#SOLID-Prinzipien) +SOLID allows to easy maintain and expand the functions of the software. + +It is based on the following princibles: +- [Single-Responsibility-Prinzip](https://de.wikipedia.org/wiki/Single-Responsibility-Prinzip) +- [Open-Closed-Prinzip](https://de.wikipedia.org/wiki/Open-Closed-Prinzip) +- [Liskov substitution principle](https://en.wikipedia.org/wiki/Liskov_substitution_principle) +- [Interface-Segregation-Prinzip](https://de.wikipedia.org/wiki/Interface-Segregation-Prinzip) +- [Dependency Inversion Prinzip](https://de.wikipedia.org/wiki/Dependency-Inversion-Prinzip) + +#### [12 factor](https://12factor.net/) +The following 12 factor allow to get the application ready for [IaaS](https://de.wikipedia.org/wiki/Everything_as_a_Service) and make it [high scalable](https://en.wikipedia.org/wiki/Scalability): + +##### I. Codebase +One codebase tracked in revision control, many deploys +##### II. Dependencies +Explicitly declare and isolate dependencies +##### III. Config +Store config in the environment +#### IV. Backing services +Treat backing services as attached resources +##### V. Build, release, run +Strictly separate build and run stages +##### VI. Processes +Execute the app as one or more stateless processes +##### VII. Port binding +Export services via port binding +##### VIII. Concurrency +Scale out via the process model +##### IX. Disposability +Maximize robustness with fast startup and graceful shutdown +##### X. Dev/prod parity +Keep development, staging, and production as similar as possible +##### XI. Logs +Treat logs as event streams +##### XII. Admin processes +Run admin/management tasks as one-off processes + +## Tested +The software MUST be automized tested by the following tests: + +- [Functional tests](https://en.wikipedia.org/wiki/Functional_testing) +- [Integration tests](https://de.wikipedia.org/wiki/Integrationstest) +- [Unit Tests](https://en.wikipedia.org/wiki/Unit_testing) + +A test coverage of 100% must be reached. + +### Continues Integration +The software MUST be [continues integrated](https://de.wikipedia.org/wiki/Kontinuierliche_Integration). + +### Applications +The application is a merge out of two indepentend applications. +#### Core Application +More informations you will find in the [symfony README.md](./symfony/README.md) + +This software offers the following interfaces: +##### [REST](https://de.wikipedia.org/wiki/Representational_State_Transfer) +This interface allows a client, which can be e.g. a Java Application or an SPA to process the domain logic. + +##### HTML +This interface offers an static GUI which allows the user to execute basic tasks. + +#### Single Page Application +This application offers a [SPA](https://en.wikipedia.org/wiki/Single-page_application) on the base of [Vue.js](https://vuejs.org/) to allow a good and dynamic user experience. + +More informations you will find in the [node README.md](./node/README.md) diff --git a/application/symfony/README.md b/application/symfony/README.md index 1f664d0..03872a1 100644 --- a/application/symfony/README.md +++ b/application/symfony/README.md @@ -1,34 +1,43 @@ -## backend application +# Core Application -## conventions +## Conventions -### coding +### Symfony +The application MUST use [Symfony 4. coding standards](https://symfony.com/doc/current/contributing/code/standards.html). -#### symfony -The application MUST use Symfony 4. coding standards - -#### php +### PHP PHP code MUST follow the [PSR-4](https://www.php-fig.org/psr/psr-4/) standard. -#### twig +### Twig Twig templates MUST follow the [Symfony Template best practices](https://symfony.com/doc/current/best_practices/templates.html). -### naming +### Naming -#### interfaces +#### Interfaces A Interfaces MUST be named *ClassnameInterface*. It SHOULD be based in the directory of the class. -#### abstract classes +Each class SHOULD implement an interface. + +#### Abstract Classes A abstract class MUST be named *AbstractClassname*. It SHOULD be based in the directory of the classes which inherit from it. -###### entities +## Technologies +The following Symfony related components will be used: +- [Services](https://symfony.com/doc/current/service_container.html) +- [ORM](https://symfony.com/doc/current/doctrine.html) +- [Routing](https://symfony.com/doc/current/routing.html) +- [Form](https://symfony.com/doc/current/forms.html) +- [Validation](https://symfony.com/doc/current/validation.html) +- [Events](https://symfony.com/doc/current/event_dispatcher.html) +- [Twig](https://twig.symfony.com/) +- [REST](https://symfony.com/doc/master/bundles/FOSRestBundle/index.html) +- [User Bundle](https://symfony.com/doc/current/bundles/FOSUserBundle/index.html) -####### source - -A source MUST be named *SourcenameSource*. +## Domain +More information about the domain logic you will find in [./src/Domain/README.md](./src/Domain/README.md).