Merge branch 'master' into feature/mp-6047-product-approval-process

_data/sidebars/scos_dev_sidebar.yml

@@ -4476,8 +4476,8 @@ entries:
         url: /docs/scos/dev/architecture/module-api/using-composer-constraint-for-customized-modules.html
       - title: Performance and Scalability
         url: /docs/scos/dev/architecture/module-api/performance-and-scalability.html
-      - title: Definition of Module API
-        url: /docs/scos/dev/architecture/module-api/definition-of-module-api.html
+      - title: "Declaration of module APIs: Public and private"
+        url: /docs/scos/dev/architecture/module-api/declaration-of-module-apis-public-and-private.html
       - title: Semantic Versioning- Major vs. Minor vs. Patch Release
         url: /docs/scos/dev/architecture/module-api/semantic-versioning-major-vs.-minor-vs.-patch-release.html
     - title: Code buckets
@@ -4497,6 +4497,22 @@ entries:
         url: /docs/scos/dev/guidelines/coding-guidelines/secure-coding-practices.html
       - title: Code style guide
         url: /docs/scos/dev/guidelines/coding-guidelines/code-style-guide.html
+    - title: Keeping a project upgradable
+      url: /docs/scos/dev/guidelines/keeping-a-project-upgradable/keeping-a-project-upgradable.html
+      nested:
+        - title: Upgradability guidelines
+          url: /docs/scos/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/upgradability-guidelines.html
+          nested:
+            - title: Entity name is not unique
+              url: /docs/scos/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/entity-name-is-not-unique.html
+            - title: Private API is extended
+              url: /docs/scos/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/private-api-is-extended.html
+            - title: Private API is used on the project level
+              url: /docs/scos/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/private-api-is-used-on-the-project-level.html
+            - title: Private API method is overridden on the project level
+              url: /docs/scos/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/private-api-method-is-overridden-on-the-project-level.html
+        - title: Running the Evalutor tool
+          url: /docs/scos/dev/guidelines/keeping-a-project-upgradable/running-the-evaluator-tool.html
     - title: Performance guidelines
       nested:
       - title: General performance guidelines

docs/scos/dev/architecture/module-api/declaration-of-module-apis-public-and-private.md

@@ -0,0 +1,69 @@
+---
+title: "Declaration of module APIs: Public and private"
+description: This document declares what public and private APIs are
+last_updated: Sep 27, 2021
+originalLink: https://documentation.spryker.com/2021080/docs/definition-api
+originalArticleId: d86471b1-719e-4ab5-b5eb-b5e915f0a837
+template: concept-topic-template
+redirect_from:
+  - /2021080/docs/definition-api
+  - /2021080/docs/en/definition-api
+  - /docs/definition-api
+  - /docs/en/definition-api
+  - /v6/docs/definition-api
+  - /v6/docs/en/definition-api
+  - /v5/docs/definition-api
+  - /v5/docs/en/definition-api
+  - /v4/docs/definition-api
+  - /v4/docs/en/definition-api
+  - /v3/docs/definition-api
+  - /v3/docs/en/definition-api
+  - /v2/docs/definition-api
+  - /v2/docs/en/definition-api
+  - /v1/docs/definition-api
+  - /v1/docs/en/definition-api
+  - /docs/scos/dev/architecture/module-api/definition-of-module-api.html
+---
+
+According to [Semantic Versioning](http://semver.org/), we release a major version of a module when there are backward compatibility(BC) breaking changes in the Public API. This document declares what public and private APIs are.
+
+## Public API
+
+In the Spryker Commerce OS’s core, the following is the public API:
+
+* Public methods in these locatable classes:
+    * [Facades](/docs/scos/dev/back-end-development/zed/business-layer/facade/facade.html)
+    * [Clients](/docs/scos/dev/back-end-development/client/client.html)
+    * [Query Containers](/docs/scos/dev/back-end-development/zed/persistence-layer/query-container/query-container.html)
+    * [Services](/docs/scos/dev/back-end-development/messages-and-errors/registering-a-new-service.html)
+
+* Interfaces:
+    * Plugin interfaces
+    * Plugins
+
+* Other classes:
+    * module Config [`Client/Yves/Zed/Shared/Service`](/docs/scos/dev/back-end-development/data-manipulation/configuration-management.html)
+    * Controllers
+    * Twig functions
+    * [CLI commands](/docs/scos/dev/back-end-development/console-commands/implementing-a-new-console-command.html)
+    * Public constants that define environment configuration in [Constant Interfaces](/docs/scos/dev/back-end-development/data-manipulation/configuration-management.html)
+* [Database](/docs/scos/dev/back-end-development/zed/persistence-layer/database-schema-definition.html)
+* Search
+* [Storage](/docs/scos/dev/back-end-development/client/using-and-configuring-redis-as-a-key-value-storage.html)
+* [Transfer objects](/docs/scos/dev/back-end-development/data-manipulation/data-ingestion/structural-preparations/creating-using-and-extending-the-transfer-objects.html)
+* Dependencies to open source components
+* Glossary keys
+* Software design
+
+
+
+### BC breaking changes
+
+There are several classes and files which are part of the public API, but not every change in the file  causes a BC break. In general, there is a BC break whenever an existing contract is changed. A contract is what the user of the API expects. This includes the signature of methods as well as the expected behavior. For this reason, we have added an ApiDoc to the most used APIs like facades and plugin interfaces.
+
+We always try to avoid BC breaking changes and reduce the effort needed to upgrade a module to a new version. There are several ways to add functionality to APIs without a BC break. So it is possible to add new methods and even parameters to the existing methods as long as they are optional.
+
+
+## Private API
+
+The *public API* term is introduced by Semantic Versioning. To refer to everything that is not part of the public API in Spryker Commerce OS, we introduced a *private API*.

docs/scos/dev/back-end-development/extending-spryker/development-strategies/development-strategies.md

@@ -14,10 +14,10 @@ Before proceeding to the strategies definition, check out the following table of
 | DEVELOPMENT STRATEGY | SPYKER OS UPDATE SUPPORT |
 | --- | --- |
 | Configuration | High, you can safely take minor and patch releases. |
-| Plug and Play | High, you can safely take minor and patch releases. |
-| Project Modules | High, you can safely take minor and patch releases. |
-| Spryker OS Module Customization | Reduced, manual check is needed for every update. |
-| Spryker OS Module Replacement | No support. |
+| Plug and play | High, you can safely take minor and patch releases. |
+| Project modules | High, you can safely take minor and patch releases. |
+| Spryker OS module customization | Reduced, manual check is needed for every update. |
+| Spryker OS module replacement | No support. |
 
 ## Development strategies
 
@@ -44,7 +44,7 @@ In your project, you don’t calculate a refundable amount inside Spryker OS, so
 
 Spryker OS support: High, you can safely take minor and patch releases.
 
-### Plug and Play
+### Plug and play
 
 When existing OOTB functionality is not enough, we need to consider building our Plugins for existing plugin stacks in separate Project modules.
 
@@ -72,7 +72,7 @@ In my Project, we would like to introduce Product Label groups. In this case, I
 
 Spryker OS support: High, you can safely take minor and patch releases.
 
-### Spryker OS Module Customization
+### Spryker OS module customization
 
 When specific OOTB Spryker behavior doesn’t fit Project requirements, you can enable the full power of available for your codebase by extending existing business modules.
 
@@ -92,7 +92,7 @@ In my Project, Order entity should not be hydrated during the buying process (we
 
 Spryker OS support: Reduced, manual check is needed for every update.
 
-### Spryker OS Module Replacement
+### Spryker OS module replacement
 
 When an existing Spryker module provides functionality that doesn’t fit the Project conceptually, there is a possibility to replace a Spryker module completely using the “composer replace” feature.
 

docs/scos/dev/upgradability-services/evaluator-tool-overview.md → docs/scos/dev/guidelines/keeping-a-project-upgradable/keeping-a-project-upgradable.md

@@ -1,41 +1,53 @@
 ---
-title: evaluator tool overview
-description: Functionalities of the evaluator tool
-last_updated: Nov 25, 2021
+title: Keeping a project upgradable
+description: Tools and guidelines for keeping a project upgradable
 template: concept-topic-template
 ---
 
-The evaluator tool is a part of Spryker SDK that performs automated quality checks against our own and industry standards.
+Keeping software up to date is a known concern, especially when it comes to transactional business models with sophisticated requirements.
 
-## How the evaluator tool works
+We established development customization guidelines to make sure that you build and always keep your project upgradable while continuing to benefit from Spryker customization flexibility.
 
-The evaluator tool performs a number of checks that are based on the static analysis of our tools. Currently, it performs the following checks:
+Following these guidelines throughout your development lifecycle is key to an effortless upgrade experience, even when your business requires highly complex customizations.
 
-* Is not unique:
-  * Transfer
-  * Transfer property
-  * Database table
-  * Database column
-  * Method
-  * Constant
-* Method is overridden:
-  * Factory
-  * Dependecy provider
-  * Repository
-  * Entity manager
-* Non-public API class was extended or used
+By keeping your project compliant with our development guidelines, you make sure that you can take minor and patch updates without breaking anything. Additionally, if your project is enrolled into [PaaS+](https://spryker.com/en/paas-plus/), being compatible enables you to take the updates *automatically*.
 
-The evaluator tool provides informative output about your code. If all the checks are successful, the tool returns zero messages.
+The following steps will help you understand what development strategies you can implement  how they affect upgradability, and what you need to do to keep your project upgradable.
+
+## 1. Select a development strategy
+
+A development strategy is the approach you follow when customizing a project. When choosing a strategy, take into account how it will affect the upgradability of your project.
+
+To keep your project upgradable, we recommend using the following development strategies:
+
+* Configuration
+* Plug and play
+* Project modules
+
+For more information about the strategies and how they affect upgradability, see [Development strategies](/docs/scos/dev/back-end-development/extending-spryker/development-strategies/development-strategies.html).
+
+
+## 2. Follow development guidelines
+
+The best way to resolve compatibility issues is to prevent them. Throughout the development cycle, we recommend following our [Project development guidelines](/docs/scos/dev/guidelines/project-development-guidelines.html).
+
+## 3. Check if project is upgradable using the Evaluator tool
+
+The Evaluator tool is part of Spryker SDK that performs a number of checks based on the static code analysis of our tools.
+
+Evaluator provides informative output about your code. If all the checks are successful, the tool returns zero messages.
 
 Evaluation example without compliance errors:
 
 ```bash
 Total messages: 0
 ```
 
-If one or more checks fail, the tool returns errors per check.
+If one or more checks fail, Evaluator returns errors per check.
+
+<details open>
+    <summary>Evaluation example with compliance errors</summary>
 
-Evaluation example with compliance errors:
 ```bash
 ...
 NotUnique:Constant Pyz\Shared\ContentBannerGui\ContentBannerGuiConfig::WIDGET_TEMPLATE_DISPLAY_NAME_SLIDER_WITHOUT_LINK name has to have project namespace, like PYZ_WIDGET_TEMPLATE_DISPLAY_NAME_SLIDER_WITHOUT_LINK.
@@ -57,13 +69,17 @@ PrivateApi:PrivateApiDependencyInBusinessModel Please avoid usage of Spryker\Zed
 PrivateApi:MethodIsOverwritten Please avoid usage of core method Spryker\Client\Kernel\AbstractFactory::getConfig() in the class Pyz\Client\ExampleProductSalePage\ExampleProductSalePageFactory
 ------------------------------ ----------------------------------------------------------------------------------------------------
 ...
-Total messages: 244
+Total messages: 11
 
-```
+```    
 
-## Using the evaluator tool
+</details>
+
+
+### Using the evaluator tool
 
 You can use the evaluator tool as follows:
+
 * Analyze project code compliance:
 ```bash
 analyze:php:code-compliance
@@ -74,9 +90,12 @@ analyze:php:code-compliance
 analyze:php:code-compliance-report
 ```
 
-For detailed instructions, see [Running the evaluator tool](/docs/scos/dev/upgradability-services/running-the-evaluator-tool.html).
+For detailed instructions, see [Running the evaluator tool](/docs/scos/dev/guidelines/keeping-a-project-upgradable/running-the-evaluator-tool.html).
+
+## 4. Resolve the evaluation issues
 
+If Evaluator detects compliance issues, resolve them by using the instructions in [Upgradability guidelines](/docs/scos/dev/guidelines/keeping-a-project-upgradable/upgradability-guidelines/upgradability-guidelines.html).
 
-## Next steps
+## 5. Update your project
 
-[Running the evaluator tool](/docs/scos/dev/upgradability-services/running-the-evaluator-tool.html)
+After passing an evaluation successfully, you can safely take minor and patch updates. If the project is enrolled into PaaS+, the updates will be provided automatically.