Skip to content

Magento module README.md

Dmitry Shevtsov edited this page Nov 21, 2022 · 6 revisions

Magento is a modular system and any external developer would like to have at least a short overview of each module explaining the module's functionality and details that the developer should know about it.

This article contains recommendations for Magento contributors about typical README.md content.

Why do you need to follow a template

Each README.md will be published in Module Reference Guide (MRG) without changes. The Documentation team uses Markdown-based software to generate the documentation website, which is why special formatting must be followed (headings, lists, etc).

General principles

Each Magento module must contain README.md.

Each README must follow the formatting described in this article.

Each README must contain the informational structure described in this article.

Title and overview

Heading 1 shows the name of the module.

# Magento_ConfigurableProductStaging module

Para #1. Add a short description of a module's purpose.

The Magento_ConfigurableProductStaging module enables you to add the Configurable Product updates to the existing store campaigns.

Para #2. Add short description of features that the module adds to Magento.

The Magento_ConfigurableProductStaging module is a part of the staging functionality in Commerce. The module adds the “Configurations” tab and the configuration wizard to the Schedule Update form of a product. You can change the Configurable Product attributes in campaigns. These updates are shown on the campaign dashboard.

Installation details

Describe important installation or uninstallation details that an external developer should be aware of.

If there is nothing to tell about, skip this section.

## Installation details

The Magento_ConfigurableProductStaging module makes irreversible changes in a database during installation. You cannot disable or uninstall this module.

For information about a module installation, see [Enable or disable modules](https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/tutorials/manage-modules.html).

Structure

Describe components that are not typical for a Magento module, if available.

Add a link to developer documentation describing the typical file structure of a module.

If there is nothing to tell about, skip this section.

## Structure

`Customers/` - the directory that declares Customers' metadata used by the module.

For information about a typical file structure of a module in Magento 2, see [Module file structure](https://developer.adobe.com/commerce/php/development/build/component-file-structure/#module-file-structure).

Extensibility

Describe extension points of the module and add links to the corresponding documentation.

If there is nothing to tell about, skip this section.

## Extensibility

Extension developers can interact with the Magento_ConfigurableProductStaging module. For more information about the Magento extension mechanism, see [Magento plug-ins](https://developer.adobe.com/commerce/php/development/components/plugins/).

[The Magento dependency injection mechanism](https://developer.adobe.com/commerce/php/development/components/plugins/) enables you to override the functionality of the Magento_ConfigurableProductStaging module.

Events

Add a list of events dispatched by the module.

If there is nothing to tell about, skip this section.

### Events

The module dispatches the following events:

 - `catalog_category_prepare_save` event in the `\Magento\CatalogStaging\Model\Category\Hydrator::hydrate()` method. Parameters:
   - `category` is a category to be saved (`\Magento\Catalog\Model\Category` class).
   - `request` is a request object with the `\Magento\Framework\App\RequestInterface` interface.
 - `controller_action_catalog_product_save_entity_after` event in the `\Magento\CatalogStaging\Model\Product\Hydrator::hydrate()` method. Parameters:
   - `controller` is a hydrator object (`\Magento\CatalogStaging\Model\Product\Hydrator`).
   - `product` is a product object (`\Magento\Catalog\Model\Product` class.

For information about an event in Magento 2, see [Events and observers](https://developer.adobe.com/commerce/php/development/components/events-and-observers/#events).

Layouts

Tell whether the module introduces layouts or layout handles, and where to find them in the module.

If the module introduces a basic layout handle that includes many layout handles, add its module relative path with a short description of a basic layout handle.

If there is nothing to tell about, skip this section.

### Layouts

The module introduces layout handles in the `view/adminhtml/layout` directory.

For more information about a layout in Magento 2, see the [Layout documentation](https://developer.adobe.com/commerce/frontend-core/guide/layouts/).

UI components

Tell whether the module introduces UI components or the configuration files, and where to find them in the module.

If there is nothing to tell about, skip this section.

### UI components

You can extend product and category updates using the configuration files located in the `view/adminhtml/ui_component` directory.

For information about a UI component in Magento 2, see [Overview of UI components](https://developer.adobe.com/commerce/frontend-core/ui-components/).

Public APIs

If the module introduces public API, describe what services are introduced.

If there is nothing to tell about, skip this section.

### Public APIs

`\Magento\Sales\Api\InvoiceOrderInterface`:

  - create an invoice document (full or partial)
  - capture money placed with order payment
  - notify a customer about document creation
  - change order status and state

`\Magento\Sales\Api\RefundInvoiceInterface`:

 - create a Credit Memo (complete or partial) for a particular Invoice
 - add details about refunded items to an Order
 - change the status and state of an Order according to performed actions
 - notify a customer about performed refund operation

`\Magento\Sales\Api\RefundOrderInterface`:

 - create a Credit Memo (complete or partial) for a particular Order
 - add details about refunded items to an Order
 - change the status and state of an Order according to performed actions
 - notify a customer about performed refund operation

`\Magento\Sales\Api\ShipOrderInterface`:

 - create a shipment document (full or partial)
 - add details about shipped items into an order
 - change the status and state of an order according to performed actions
 - notify the customer of a new shipment document
 
[Learn a detailed description of the Magento_Sales API.](https://developer.adobe.com/commerce/php/module-reference/module-sales/)
 
For information about a public API in Magento 2, see [Public interfaces & APIs](https://developer.adobe.com/commerce/php/development/components/api-concepts/).

Additional information

Add any important details that cannot be added to previous sections.

If there is nothing to tell about, skip this section.

## Additional information

For information about significant changes in patch releases, see [Release information](https://experienceleague.adobe.com/docs/commerce-operations/release/notes/overview.html).

### cron options

cron group configuration can be set in `etc/crontab.xml`.

-   `staging_apply_version` – each period of time checks in a table of updates if any [campaign](#campaign) has been started and if yes, it applies all [scheduled updates](#scheduled-update) for the campaign.

-   `staging_remove_updates` – each period of time checks if a campaign contains any update, and if it is empty, deletes the campaign.

-   `staging_synchronize_entities_period` – each period of time checks if the start or end dates of a campaign have been changed. If it finds any changes, it applies the same changes to all updates dependent on the campaign.

[Learn how to configure and run cron in Magento.](https://experienceleague.adobe.com/docs/commerce-operations/configuration-guide/cli/configure-cron-jobs.html)

### Indexes and indexing modes

When an update is applied, the indexer handles it according to the actual indexing mode. In a preview mode, indexing is not applied. Data is loaded for the open page only.

[Learn more about indexing in Magento.](https://developer.adobe.com/commerce/php/development/components/indexing/)

### Data migration

The Magento_Staging module uses the `\Magento\Staging\Setup\BasicSetup` class during installation. This class changes the database schema and migrates data.

#### Migration of attributes with a range

Each update attribute that contains a time range is synchronized with the dates of the campaign. Attributes with time range are removed from the UI.

Readme format

Example of **heading, paragraph, link and path format

The following example is a complete README for a module:

# Magento_ConfigurableProductStaging module

The Magento_ConfigurableProductStaging module enables you to add the Configurable Product updates to the existing store campaigns.

The Magento_ConfigurableProductStaging module is a part of the staging functionality in Magento EE. The module adds the “Configurations” tab and the configuration wizard to the Schedule Update form of a product. You can change the Configurable Product attributes in campaigns. These updates are shown on the campaign dashboard.

## Installation details

The Magento_ConfigurableProductStaging module makes irreversible changes in a database during installation. You cannot disable or uninstall this module.

For information about a module installation in Magento 2, see [Enable or disable modules](https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/tutorials/manage-modules.html).

## Extensibility

Extension developers can interact with the Magento_ConfigurableProductStaging module. For more information about the Magento extension mechanism, see [Magento plug-ins](https://developer.adobe.com/commerce/php/development/components/plugins/).

[The Magento dependency injection mechanism](https://developer.adobe.com/commerce/php/development/components/dependency-injection/) enables you to override the functionality of the Magento_ConfigurableProductStaging module.

### Layouts

The module introduces layout handles in the `view/adminhtml/layout` directory.

For more information about a layout in Magento 2, see the [Layout documentation](https://developer.adobe.com/commerce/frontend-core/guide/layouts/).

### UI components

You can extend product and category updates using the UI components located in the `view/adminhtml/ui_component` directory.

For information about a UI component in Magento 2, see [Overview of UI components](https://developer.adobe.com/commerce/frontend-core/ui-components/).

## Additional information

For information about significant changes in patch releases, see [Release information](https://experienceleague.adobe.com/docs/commerce-operations/release/notes/overview.html).

Example of a list

### Events

You can use the following events:

- `catalog_category_prepare_save` event in the `\Magento\CatalogStaging\Model\Category\Hydrator::hydrate()` method. Parameters:
  - `category` is a category to be saved (`\Magento\Catalog\Model\Category` class).
  - `request` is a request object with the `\Magento\Framework\App\RequestInterface` interface.
- `controller_action_catalog_product_save_entity_after` event in the `\Magento\CatalogStaging\Model\Product\Hydrator::hydrate()` method. Parameters:
  - `controller` is a hydrator object (`\Magento\CatalogStaging\Model\Product\Hydrator`).
  - `product` is a product object (`\Magento\Catalog\Model\Product` class.