Missing documentation items for Symfony migration

matks commented 5 years ago

Here's a list of things we need to document (the list will evolve in time)

Related to Grid

[x] How to use reusable Javascript grid Extensions https://github.com/PrestaShop/docs/pull/240
[x] How to add bulk actions to a grid https://github.com/PrestaShop/docs/pull/244
[x] How link actions work (see https://github.com/PrestaShop/docs/pull/244#issuecomment-482580858)

Related to Symfony (focus on controller / app layer of the migration)

[x] Reusable PrestaShop form types
[x] PrestaShop console commands
[ ] How to create a new page / controller (step-by-step tutorial), listing and CRUD
[x] How to use composition and SF services to extend PrestaShop behavior
[ ] Overview of the main services being used in PrestaShop
[ ] Twig folder structure and usage
[ ] Prestashop twigs macros and UI-Kit usage
[ ] Thin controller, fat models
[ ] Internal usage of roles for PrestaShop, linked with security
[x] About Identifiable Objects forms https://github.com/PrestaShop/docs/pull/184
[ ] Improve "settings form" doc (see https://github.com/PrestaShop/docs/pull/184#issuecomment-481714552)
[x] Reusable PrestaShop form types https://github.com/PrestaShop/docs/pull/245

Related to CQRS (focus on domain / core layer of the migration)

[x] What is CQRS https://github.com/PrestaShop/docs/pull/232
[ ] Focus on CQRS being used by PrestaShop: legacy handlers layer
[x] Use of ValueObjects and DTOs (related to CQRS)
[x] Using Domain Exceptions and how to handle them https://github.com/PrestaShop/docs/pull/255
[x] What is the usage of Adapter namespace and its content

Related to new Admin Theme

[ ] A zoom on how we use webpack
[ ] Using scss

Related to testing

[x] Writing unit tests
[x] Writing behat tests
[x] Writing puppeeter tests (soon)

zuk3975 commented 5 years ago

How to use reusable Javascript grid Extensions https://github.com/PrestaShop/docs/pull/240

sarjon commented 5 years ago

overview of the main services being used in PrestaShop

What are these? :thinking:

twig folder structure and usage using scss thin controller, fat models internal usage of roles for PrestaShop, linked with security a zoom on how we use webpack using Domain Exceptions and how to handle them use of ValueObjects and DTOs (related to CQRS)

Can you explain these what you mean?

how to use composition and SF services to extend PrestaShop behavior

Is this in context of module development or PrestaShop customization (either by creating custom bundle or adding new services to core)?

matks commented 5 years ago

overview of the main services being used in PrestaShop I was thinking about the SF and 3rd party we are using and how they are being used. Example: -- we use symfony form types -- we do not use Doctrine -- we use Tactician command bus -- we use Twig and some custom extensions -- we do not use symfony translator -- we use symfony security configured for us
twig folder structure and usage Main folder for a template will be built following the Page location in the BO (example: Sell > Catalog > Manufacturer), in there we usually have main templates (add.html.twig ...) and a subfolder Blocks ...
using scss An introduction of what is scss, why and how we use it in prestashop. A short explanation and some links to scss doc. Idea is to answer to "hey, I want to contribute to PS css but I dont understand what is this scss thing ?"
thin controller, fat models This is a standard best practice where you try to avoid business logic from Controllers. As it was not followed in legacy controllers, I think it's good to re-explain it, what value it brings (and we do it in controllers by delegating business logic to services).
internal usage of roles for PrestaShop, linked with security Basically, it explains to a developer what are the CREATE, READ, UPDATE and DELETE rights used by PrestaShop for each page/tab, how to grant them (from Permissions page), and how this is being implemented using Symfony Security Voter
a zoom on how we use webpack Same as for scss: "hey, I want to contribute to the admin theme but I dont understand, I modified the SCSS file and I cant see my change" => short explanation of webpack, what it does, why we use it, then links to official webpack doc
using Domain Exceptions and how to handle them Explanation of why we have so many Exceptions (I say this on purpose because actually a lot of php projects dont use custom Exceptions), show how a developer can benefit from it and provide a usecase of "I want to handle exception A but not B"
use of ValueObjects and DTOs (related to CQRS) A reminder of what are VOs, what are DTOs, why we use them instead of arrays and StdClass

how to use composition and SF services to extend PrestaShop behavior

Is this in context of module development or PrestaShop customization (either by creating custom bundle or adding new services to core)? Both, but first I need to discuss with @eternoendless whether we can talk publicly about Symfony services override as an extensibility mechanism or not.

sarjon commented 5 years ago

Additional topics to document:

Reusable PrestaShop form types
PrestaShop console commands

rokaszygmantas commented 5 years ago

Using Domain Exceptions and how to handle them https://github.com/PrestaShop/docs/pull/255

zuk3975 commented 5 years ago

Reusable PrestaShop form types #245

sarjon commented 5 years ago

We mark some classes and methods (mostly adapters) with @internal tag. However, I believe that it's not clear for most of the community what they mean, so I suggest to document them and explain how we use them, wdyt @matks?

matks commented 5 years ago

@sarjon good idea 👍 you can link it to http://docs.phpdoc.org/references/phpdoc/tags/internal.html

matks commented 5 years ago

🆙 to @matks myself

matks commented 3 years ago

Updated

PrestaShop / docs