#148 Update documentation according to Symfony best practices

Author: njoubert-cleverage

CONTRIBUTING.md

@@ -1,10 +1,50 @@
 Contributing
 ============
 
-Every contributions are welcomed. This bundle aims to provide a standalone set of generic component. 
-If a contribution is too specific or requires dependencies, it might be put in a separated sub-bundle.
+First of all, **thank you** for contributing, **you are awesome**!
 
-Ideally every PR should contain documentation and unit test updates.
+Here are a few rules to follow in order to ease code reviews, and discussions before
+maintainers accept and merge your work.
+
+You MUST run the quality & test suites.
+
+You SHOULD write (or update) unit tests.
+
+You SHOULD write documentation.
+
+Please, write [commit messages that make sense](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),
+and [rebase your branch](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) before submitting your Pull Request.
+
+One may ask you to [squash your commits](https://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html)
+too. This is used to "clean" your Pull Request before merging it (we don't want
+commits such as `fix tests`, `fix 2`, `fix 3`, etc.).
+
+Thank you!
+
+## Running the quality & test suites
+
+Tests suite uses Docker environments in order to be idempotent to OS's. More than this
+PHP version is written inside the Dockerfile; this assures to test the bundle with
+the same resources. No need to have PHP installed.
+
+You only need Docker set it up.
+
+To allow testing environments more smooth we implemented **Makefile**.
+You have two commands available:
+
+```bash
+make quality
+```
+
+```bash
+make tests
+```
+
+which will execute all tests inside the docker.
+
+```bash
+make test TEST="Tests/Util/FilenameUtilsTest.php"
+```
 
 ## Deprecations notices
 
@@ -14,4 +54,5 @@ When a feature should be deprecated, or when you have a breaking change for a fu
 * Trigger a deprecation error: `@trigger_error('This feature will be deprecated in v4.0', E_USER_DEPRECATED);`
 
 You can check which deprecation notice is triggered in tests
+* `make bash`
 * `SYMFONY_DEPRECATIONS_HELPER=0 ./vendor/bin/phpunit`

Makefile

@@ -37,6 +37,8 @@ bash: #[Docker] Connect to php container with current host user
 logs: #[Docker] Show logs
 	$(DOCKER_COMPOSE) logs -f
 
+quality: phpstan php-cs-fixer rector #[Quality] Run all quality checks
+
 phpstan: #[Quality] Run PHPStan
 	$(DOCKER_RUN_PHP) "vendor/bin/phpstan --no-progress --memory-limit=1G analyse"
 
@@ -46,5 +48,7 @@ php-cs-fixer: #[Quality] Run PHP-CS-Fixer
 rector: #[Quality] Run Rector
 	$(DOCKER_RUN_PHP) "vendor/bin/rector"
 
+tests: phpunit #[Tests] Run all tests
+
 phpunit: #[Tests] Run PHPUnit
 	$(DOCKER_RUN_PHP) "vendor/bin/phpunit"

README.md

@@ -1,8 +1,6 @@
 CleverAge/ProcessBundle
 =======================
 
-## Introduction
-
 This bundle allows to configure series of tasks to be performed on a certain order.
 Basically, it will greatly ease the configuration of import and exports but can do much more.
 
@@ -12,144 +10,8 @@ Demo project can be found on [there](https://github.com/cleverage/process-bundle
 
 ## Documentation
 
-- [Quick start](doc/01-quick_start.md)
-- [Task types](doc/02-task_types.md)
-- [Custom tasks and development](doc/03-custom_tasks.md)
-- [Advanced workflow](doc/04-advanced_workflow.md)
-- Cookbooks
-  - [Common Setup](doc/cookbooks/01-common_setup.md)
-  - [Transformations]
-  - [Flow manipulation]
-  - [Dummy tasks]
-  - [Debugging]
-  - [Logging]
-  - [Subprocess]
-  - [File manipulation]
-  - [Direct call (in controller)]
-  - [Performances monitoring](doc/cookbooks/performances_monitoring.md)
-  - [Memory usage analysis](doc/cookbooks/memory_usage_graph.md)
-- Reference
-  - [Process definition](doc/reference/01-process_definition.md)
-  - [Task definition](doc/reference/02-task_definition.md)
-  - Basic and debug
-    - [ConstantOutputTask](doc/reference/tasks/constant_output_task.md)
-    - [ConstantIterableOutputTask](doc/reference/tasks/constant_iterable_output_task.md)
-    - [CounterTask]
-    - [DebugTask](doc/reference/tasks/debug_task.md)
-    - [DieTask](doc/reference/tasks/die_task.md)
-    - [DummyTask](doc/reference/tasks/dummy_task.md)
-    - [ErrorForwarderTask]
-    - [EventDispatcherTask](doc/reference/tasks/event_dispatcher_task.md)
-    - [MemInfoDumpTask]
-    - [StopwatchTask]
-  - Data manipulation and transformations
-    - [DenormalizerTask](doc/reference/tasks/denormalizer_task.md)
-    - [NormalizerTask](doc/reference/tasks/normalizer_task.md)
-    - [DeserializerTask]
-    - [SerializerTask]
-    - [PropertyGetterTask](doc/reference/tasks/property_getter_task.md)
-    - [PropertySetterTask](doc/reference/tasks/property_setter_task.md)
-    - [ObjectUpdaterTask]
-    - [SplitJoinLineTask]
-    - [TransformerTask](doc/reference/tasks/transformer_task.md)
-    - [ValidatorTask]
-  - File/CSV
-    - [CsvReaderTask](doc/reference/tasks/csv_reader_task.md)
-    - [CsvWriterTask](doc/reference/tasks/csv_writer_task.md)
-    - [CSVSplitterTask]
-    - [InputCsvReaderTask]
-  - File/JsonStream
-    - [JsonStreamReaderTask]
-  - File/XML
-    - [XmlReaderTask](doc/reference/tasks/xml_reader_task.md)
-    - [XmlWriterTask](doc/reference/tasks/xml_writer_task.md)
-  - File/Yaml
-    - [YamlReaderTask]
-    - [YamlWriterTask]
-  - File
-    - [FileMoverTask]
-    - [FileReaderTask]
-    - [FileRemoverTask]
-    - [FileWriterTask]
-    - [FolderBrowserTask]
-    - [InputFolderBrowserTask]
-  - Flow manipulation
-    - [AggregateIterableTask](doc/reference/tasks/aggregate_iterable_task.md)
-    - [InputAggregatorTask](doc/reference/tasks/input_aggregator_task.md)
-    - [InputIteratorTask](doc/reference/tasks/input_iterator_task.md)
-    - [ArrayMergeTask]
-    - [ColumnAggregatorTask]
-    - [RowAggregatorTask]
-    - [FilterTask]
-    - [GroupByAggregateIterableTask]
-    - [SimpleBatchTask]
-    - [IterableBatchTask]
-    - [SkipEmptyTask]
-    - [StopTask]
-  - Process
-    - [CommandRunnerTask]
-    - [ProcessExecutorTask]
-    - [ProcessLauncherTask]
-  - Reporting
-    - [AdvancedStatCounterTask]
-    - [LoggerTask]
-    - [StatCounterTask]
-  - Transformers
-    - Basic and debug
-      - [CachedTransformer]
-      - [CallbackTransformer]
-      - [CastTransformer]
-      - [ConstantTransformer]
-      - [ConvertValueTransformer]
-      - [DebugTransformer]
-      - [DefaultTransformer]
-      - [GenericTransformer]
-      - [EvaluatorTransformer]
-      - [ExpressionLanguageMapTransformer]
-      - [MappingTransformer](doc/reference/transformers/mapping_transformer.md)
-      - [MultiReplaceTransformer]
-      - [PregFilterTransformer]
-      - [RulesTransformer](doc/reference/transformers/rules_transformer.md)
-      - [TypeSetterTransformer]
-      - [UnsetTransformer]
-      - [WrapperTransformer]
-    - Array
-      - [ArrayElementTransformer]
-      - [ArrayFilterTransformer](doc/reference/transformers/array_filter_transformer.md)
-      - [ArrayFirstTransformer]
-      - [ArrayLastTransformer]
-      - [ArrayMapTransformer]
-      - [ArrayUnsetTransformer]
-    - Date
-      - [DateFormatTransformer](doc/reference/transformers/date_format.md)
-      - [DateParserTransformer](doc/reference/transformers/date_parser.md)
-    - Object
-      - [InstantiateTransformer]
-      - [PropertyAccessorTransformer]
-      - [RecursivePropertySetterTransformer]
-    - Serialization
-      - [DenormalizeTransformer]
-      - [NormalizeTransformer]
-    - String
-      - [ExplodeTransformer]
-      - [HashTransformer]
-      - [ImplodeTransformer]
-      - [SlugifyTransformer]
-      - [SprintfTransformer]
-      - [TrimTransformer]
-    - XML
-      - [XpathEvaluatorTransformer](doc/reference/transformers/xpath_evaluator.md)
-  - Other bridges
-    - [Doctrine](https://github.com/cleverage/doctrine-process-bundle)
-    - [Eav](https://github.com/cleverage/eav-process-bundle)
-    - [Soap](https://github.com/cleverage/soap-process-bundle)
-    - [Another Soap](https://github.com/cleverage/process-soap-bundle)
-    - [Rest](https://github.com/cleverage/rest-process-bundle)
-    - [Enqueue](https://github.com/cleverage/enqueue-process-bundle)
-    - [Flysystem](https://github.com/cleverage/flysystem-process-bundle)
-    - [Cache](https://github.com/cleverage/cache-process-bundle)
-  - [Generic transformers definition](doc/reference/03-generic_transformers_definition.md)
-- [UI](https://github.com/cleverage/processuibundle)
+For usage documentation, see:
+[docs/index.md](doc/index.md)
 
 ## Support & Contribution
 

docs/01-quick_start.md

@@ -20,13 +20,16 @@ The most common example is the ETL. It's a kind of application whose main purpos
 
 ## Installation
 
-This bundle requires Symfony 6.3 minimum. You can install it using composer:
+Make sure Composer is installed globally, as explained in the [installation chapter](https://getcomposer.org/doc/00-intro.md)
+of the Composer documentation.
+
+Open a command console, enter your project directory and install it using composer:
 
 ```bash
 composer require cleverage/process-bundle
 ```
 
-Remember to add the following line to bundles.php (not required if Symfony Flex is used)
+Remember to add the following line to config/bundles.php (not required if Symfony Flex is used)
 
 ```php
 CleverAge\ProcessBundle\CleverAgeProcessBundle::class => ['all' => true],
@@ -97,11 +100,11 @@ Then you can add tasks in this array. They consist of a `service`, optionally co
 ```
 
 Below you can see a minimal working ETL example. It consist of 3 tasks:
-- the first *extract* some data (the [constant output task](./reference/tasks/constant_output_task.md) outputs... a constant value): it's an array with 3 
+- the first *extract* some data (the [constant output task](reference/tasks/constant_output_task.md) outputs... a constant value): it's an array with 3 
 keys/values
-- the second *transform* the given value (the [transformer task](./reference/tasks/transformer_task.md) is one of the most important!): the output is then an 
+- the second *transform* the given value (the [transformer task](reference/tasks/transformer_task.md) is one of the most important!): the output is then an 
 array with 2 keys/values, created using the value from previous task
-- finally, the last will just display the result (it's a cheap *load*, using the [debug task](./reference/tasks/debug_task.md), only for development 
+- finally, the last will just display the result (it's a cheap *load*, using the [debug task](reference/tasks/debug_task.md), only for development 
 purpose!)
 
 ```yaml
@@ -193,4 +196,4 @@ Once everything is working fine, you may want to automate your processes. The st
 
 To check if everything went fine, logs are stored in database:
 - `clever_process_history`: logs process started, with `process_code`, `start_date`, `end_date` and `statut`
-- `clever_task_history`: logs custom tasks logs (see [logging]()), with `task_code`, `message`, `logged_at` date, `level`, a `reference` and `context`
+- `clever_task_history`: logs custom tasks logs (see [logging]), with `task_code`, `message`, `logged_at` date, `level`, a `reference` and `context`

docs/02-task_types.md

@@ -81,7 +81,7 @@ Transformers are a special subset of this bundle. They're not tasks strictly spe
 point for Transformers is the `CleverAge\ProcessBundle\Task\TransformerTask`, whose only purpose is to take some input, 
 pass it to a transformer and transfer the output to next task.
 
-The idea is to allow a great flexibility (especially using the [MappingTransformer]()), without using too much code.
+The idea is to allow a great flexibility (especially using the [MappingTransformer]), without using too much code.
 
 They implement `CleverAge\ProcessBundle\Transformer\TransformerInterface` or 
 `CleverAge\ProcessBundle\Transformer\ConfigurableTransformerInterface`.

docs/03-custom_tasks.md

@@ -25,11 +25,11 @@ method will be called and the `$state` will contain a new input (`ProcessState::
 may pass a new output to the next task (`ProcessState::setOutput`).
 
 The State also provide reporting tools:
-* `ProcessState::log`: register a new log message (see[logging]())
+* `ProcessState::log`: register a new log message (see[logging])
 * `ProcessState::getConsoleOutput`: direct link to Symfony's Console Output (deprecated, prefer log)
 
 Sometimes, when you execute a task, you need to change how the process may continue. It will be detailed in depth in 
-the [next chapter about error management]() but here are the main methods
+the [next chapter about error management] but here are the main methods
 * `ProcessState::setSkipped`: process won't continue to next step
 * `ProcessState::setStopped`: process will fully stop
 * `ProcessState::setErrorOutput`: allow to direct an output to an error branch from your workflow
@@ -50,14 +50,14 @@ Defining your tasks as Iterable or Blocking is as simple as implementing one of
 * `CleverAge\ProcessBundle\Model\IterableTaskInterface`: the `next` method should behave almost the same as PHP's native
 [next](https://secure.php.net/manual/en/function.next.php) function for arrays (except it only returns a boolean) 
 * `CleverAge\ProcessBundle\Model\BlockingTaskInterface`: every `execute` method call should only accumulate data from 
-the input and once every previous task is _resolved_, the `proceed` method should provide an output (see [TODO]() for 
+the input and once every previous task is _resolved_, the `proceed` method should provide an output (see [TODO] for 
 the exact definition of a resolved method)
 
 It's up to you to know when you should be using one of those, but basically:
 * When you loop over a collection of independent elements, you should use an Iterable task. It may help you reduce the 
 memory footprint.
 * When you need to collect, upload, ... data as a whole, then you might need a Blocking task. Be sure to read [previous 
-chapter's notice]() about performance.
+chapter's notice] about performance.
 
 Tasks cannot be both Iterable and Blocking.