Editorial pass

design-documents/provisioning/configuration.md

@@ -2,13 +2,13 @@
 
 ### Overview
 
-When you start a new Magento project there are similar initial tasks to set up configuration including websites, stores, tax, store configuration, attributes and more. This leads to the following known problems:
+When starting a new Magento project, there are initial tasks to set up: websites, stores, tax, store configuration, attributes and more. This often leads to the following problems:
 
-* Boilerplate Code in data patches (copied from Google, DevDocs, StackOverflow, other projects, maybe poorly adjusted)
-* Update and Delete operations are tedious and complex as you have to manage relations and identification inside data patches (i.e. store code vs. autoincrement id)
-* Installation from scratch with scope level configuration inside `config.php` is not possible if you rely on it in data patches
+* Boilerplate code in data patches: code copied from Google, DevDocs, StackOverflow or other projects.
+* Update and Delete operations are tedious and complex. You must manage relations and identification inside data patches (i.e. store code vs. autoincrement id)
+* Installation from scratch, with scope level configuration inside `config.php`, is not possible if you rely on data patches
 
-There should be a declarative schema approach to provision a new instance with all necessary configuration to run. It is related to the existing delcarative database schema but manages configuration data like:
+Consider a declarative schema approach to provisioning a new instance, with all the necessary configuration set. It is related to the existing delcarative database schema, but manages configuration data such as:
 
 * Websites
 * Stores
@@ -19,42 +19,42 @@ There should be a declarative schema approach to provision a new instance with a
 * Attribute Groups
 * Tax
 
-This is at least the most basic configuration. The design approach aims to leverage the extensibility so that more configuration entities can be included in the list above.
+This is the most basic configuration. This design approach aims to leverage extensibility so more configuration entities can be included in the list above.
 
-**Additional feature:** There should also be an export functionality which generates declarative schema files for an existing Magento instance which includes all configuration. This feature would be priority 2 as it is more important to import them first via declarative schema.
+**Additional feature:** There should also be 'export' functionality, which generates declarative schema files for an existing Magento instance,including all configurations. This feature would be priority 2, as it is more important to import them first via a declarative schema.
 
 ### Design
 
 #### Module structure
 
-The main dataflow and import functionality is provided by a core module. It controls the workflow and provides generic functionality for all configuration modules. On top of that there is a module for every configuration entity (website, store, tax...) which uses the core module to import and export the data.
+The main dataflow and import functionality is provided by a core module. It controls the workflow and provides generic functionality for all configuration modules. On top of that, there is a module for every configuration entity (website, store, tax...), which uses the core module to import and export the data.
 
 ![module-structure](module-structure.jpg)
 
 The core module provides:
 
 * CLI Commands: Imports and exports single configuration entities
-* Backend GUI: Offers functionality to export configuration via admin interface
+* Backend GUI: Offers functionality to export configurations via the admin interface
 * Import / Export workflow: Abstract definition of the workflow
-* Serialize / Input / Output: Read- and write adapter, offers merge logic for declarative files and offers `maintained` flag logic
+* Serialize / Input / Output: Read- and write adapter, offers merge logic for declarative files and provides the `maintained` flag logic
 
 #### Provisioning sequence
 
-There are entities which can be declared on project scope and entities which can be declared on module scope. All project declarations belong into `app/etc`. Basically everything which can be declared on module scope can also be declared on project scope and will be overwritten by the project scope as it enforces the rules project wide and also can change module introduced entities.
+There are entities which can be declared on the project scope and entities which can be declared on the module scope. All project declarations go into `app/etc`. Basically everything which can be declared on the module scope can also be declared on the project scope and will be overwritten by the project scope, as it enforces the rules project-wide and also can change module-introduced entities.
 
 **Project declarations:**
 
 * Attribute Sets/Attribute Groups
 * Attributes
 * Websites/Stores/Store Groups
-* System configuration (basically the config.xml functionality will be used for this)
+* System configuration (the config.xml functionality is used for this)
 * Tax
 * future entities can be added...
 
 **Module declarations:**
 
 * Attributes
-* System configuration (basically the config.xml functionality will be used for this)
+* System configuration (the config.xml functionality is used for this)
 * Tax
 
 The usual behavior for installing from scratch or upgrading is the following:
@@ -81,7 +81,7 @@ The usual behavior for installing from scratch or upgrading is the following:
 * Recurring Data
 * app:config:import
 
-There is a dependency tree during installation like the following:
+There is a dependency tree during installation:
 
 * Declarative Schema 
 * Schema Patches 
@@ -97,30 +97,32 @@ There is a dependency tree during installation like the following:
 
 #### Data structure
 
-As already mentioned the data structure is related to the existing database declarative schema. Every module can define such a XML file for a configuration type. All configuration files for the same type would be merged to one big logical structure. Therefore every configuration type module should at least support merge logic. This is done individually as for example websites are merged differently than attributes.
+As already mentioned, the data structure is related to the existing database declarative schema. Every module can define a XML file for a particular configuration type. All configuration files for the same type would be merged to a single logical structure. Therefore every configuration type module should at least support merge logic. This is done individually, as for example, websites are merged differently than attributes.
 
-Therefore a virtual type of `Magento\Framework\Config\Reader\Filesystem` will be defined which has a ` Magento\Framework\Config\ConverterInterface` which is responsible for merging the XML files.
+Therefore, a virtual type of `Magento\Framework\Config\Reader\Filesystem` will be defined, which has a ` Magento\Framework\Config\ConverterInterface` which is responsible for merging the XML files.
 
-There is also a field `is_mutable` which defines if the declared data can be changed by the admin. The following explains the behavior:
+There is also a field `is_mutable`, which defines if the declared data can be changed by the admin.
 
 * `is_mutable` is not defined:
   * new entity is installed
   * checkbox is unchecked
   * admin can change the entity (after checking the checkbox)
-  * won't overwrite admin side manual created entities until checkbox is unchecked
+  * will not overwrite the admin-side, manually-created entities until the checkbox is unchecked
 * `is_mutable = false`:
   * new entity is installed
   * checkbox does not exist
-  * admin can't change the entity
-  * will overwrite admin side manual created entities
+  * admin cannot change the entity
+  * will overwrite admin-side, manually-created entities
 
 #### Example: Attribute behavior
- - "**is_mutable**" flag is checkbox at the attribute grid and at attribute edit page
- - Attributes which created from Admin panel is not maintainable by xml (no dumping, "**is_mutable**" flag is not shown but has true value in database) until xml with the same attribute code will be created and "**is_mutable**" will be unchecked
+
+ - "**is_mutable**" flag is a checkbox on the attribute grid and on the attribute edit page
+ - Attributes which are created from the admin panel are not maintainable by xml (no dumping, "**is_mutable**" flag is not shown but has a true value in database) until xml with the same attribute code is created and "**is_mutable**" will be unchecked
  - "**is_mutable**" flag is responsible for defining maintenance responsibilities:
-   - **true** responsibility on Admin panel side switchable from admin
-   - **false** responsibility on code side switchable from admin
-   - **locked** - responsibility on code side and not switchable from admin
+   - **true** responsibility is on the admin panel side, switchable from the admin
+   - **false** responsibility is on the code side, switchable from the admin
+   - **locked** - responsibility is on the code side and is not switchable from the admin
+
 ```
 <?xml version="1.0"?>
 <!--
@@ -145,10 +147,12 @@ There is also a field `is_mutable` which defines if the declared data can be cha
     </customer>
 </attributes>
 ```
+
 ## Created by XML
-- Default `"is_mutable"=false` and this property is optional for attribute xml node
+
+- Default `"is_mutable"=false`: this property is optional for the attribute XML node
 - Fully managed by admin panel
-- If xml with the same attribute code will be created - it will take over all responsibilities to a code side and will be then managed like attribute created by XML declaration
+- If XML with the same attribute code is created - it will take over all responsibilities to a code side and will be managed like an attribute created by a XML declaration
 
 | is_mutable in XML->       | `is_mutable` not defined          | `is_mutable="false"` |
 | ------------------------- | --------------------------------- | -------------------- |
@@ -160,9 +164,10 @@ There is also a field `is_mutable` which defines if the declared data can be cha
 | data patch changes        | can apply                         | will be overwritten  |
 
 
-## Created by admin (xml declaration doesn't exists):
-- Fully managed by admin panel
-- If xml with the same attribute code will be created - it will take over all responsibilities to a code side and will be then managed like attribute created by XML declaration
+## Created by admin (xml declaration does not exists)
+
+- Fully managed by the admin panel
+- If XML with the same attribute code is created, it will take over all responsibilities to the code side and will be managed like an attribute created by XML declaration
 
 * DB value for `is_mutable`: true
 * checkbox: hidden
@@ -172,6 +177,7 @@ There is also a field `is_mutable` which defines if the declared data can be cha
 * data patch changes: can apply
 
 #### Example: Store Scopes behavior
+
 We can define a `stores.xml` file on project scope like the following:
 
 ```xml
@@ -228,17 +234,20 @@ We can define a `stores.xml` file on project scope like the following:
 
 #### Change or delete configuration
 
-Changing or deleting configuration is a challenging task, especially for all the relations and true identifier of an entity (i.e. store code vs. autoincrement id). Every configuration type module should therefore define the identifier on its own, dependent on which configuration type it supports.
+Changing or deleting a configuration is a challenging task, especially with all the relations and the true identifier of an entity (i.e. store code vs. autoincrement id). Every configuration type module should therefore define the identifier on its own, dependent on which configuration type it supports.
 
 Example: Create and update store:
+
 - The store/website/store group is identified by its code
 - All other data than the code can be changed => will lead to an update
 - If the code has to change: delete entity and create new one
 
-Deletions must be done explicit similar how you explicitly deactivate a plugin with `disabled = true`. This allows for proper merging of the XML files.
+Deletions must be explicit, similar how you explicitly deactivate a plugin with `disabled = true`. This allows for the proper merging of the XML files.
 
 Example Delete store:
+
 - A `deleted=true` flag should be provided
+
 ```xml
 <store code="default"
        website_code="base"
@@ -251,7 +260,7 @@ Example Delete store:
 
 #### Extension Points and Scenarios
 
-Once the core provisioning logic and module is set up including the main workflow, we can adapt legacy code to the new functionality. For example registering themes is done via a recurring patch which we can easily adapt to the new configuration provisioning logic.
+Once the core provisioning logic and module is set up, including the main workflow, we can adapt legacy code to the new functionality. For example registering themes is done via a recurring patch which we can easily adapt to the new configuration provisioning logic.
 
 ### Prototype or Proof of Concept