Skip to content

Instantly share code, notes, and snippets.

@carlos-reynosa

carlos-reynosa/module-readme-template.md

Forked from magento-docbot/module-readme-template.md
Created January 15, 2020 20:08
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save carlos-reynosa/b285f8e6e39e14e348fdd3c7ec314fde to your computer and use it in GitHub Desktop.
Save carlos-reynosa/b285f8e6e39e14e348fdd3c7ec314fde to your computer and use it in GitHub Desktop.
Download ZIP
README template for Magento modules
Raw
module-readme-template.md

Title and overview

Heading 1 showing the name of the module.

# Magento_ConfigurableProductStaging module

Para#1. Add short description of a module 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 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

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

If there is nothing to tell about, just 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 in Magento 2, see [Enable or disable modules](http://devdocs.magento.com/guides/v2.3/install-gde/install/cli/install-cli-subcommands-enable.html).

Structure

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

Add a link to devdocs describing typical file structure of a module.

If there is nothing to tell about, just 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](http://devdocs.magento.com/guides/v2.3/extension-dev-guide/build/module-file-structure.html#module-file-structure).

Extensibility

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

If there is nothing to tell about, just 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](http://devdocs.magento.com/guides/v2.3/extension-dev-guide/plugins.html).

[The Magento dependency injection mechanism](http://devdocs.magento.com/guides/v2.3/extension-dev-guide/depend-inj.html) 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, just 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](http://devdocs.magento.com/guides/v2.3/extension-dev-guide/events-and-observers.html#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 short description of a basic layout handle.

If there is nothing to tell about, just 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](http://devdocs.magento.com/guides/v2.3/frontend-dev-guide/layouts/layout-overview.html).

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, just 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](http://devdocs.magento.com/guides/v2.3/ui_comp_guide/bk-ui_comps.html).

Public APIs

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

If there is nothing to tell about, just 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 particular Invoice
 - add details about refunded items to an Order
 - change 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 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 status and state of an order according to performed actions
 - notify the customer of a new shipment document
 
[Learn detailed description of the Magento_Sales API.](http://devdocs.magento.com/guides/v2.3/mrg/ce/Sales/services.html)
 
For information about a public API in Magento 2, see [Public interfaces & APIs](http://devdocs.magento.com/guides/v2.3/extension-dev-guide/api-concepts.html).

Additional information

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

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

See http://devdocs.magento.com/guides/v2.3/mrg/ee/Staging.html#additional-information for more complex example.

## Additional information

For information about significant changes in patch releases, see [2.3.x Release information](http://devdocs.magento.com/guides/v2.3/release-notes/bk-release-notes.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 start or end dates of a campaign have been changed. If it finds any changes, it applies same changes to all updates dependent from the campaign.

[Learn how to configure and run cron in Magento.](http://devdocs.magento.com/guides/v2.3/config-guide/cli/config-cli-subcommands-cron.html)

### Indexes and indexing modes

When 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.](http://devdocs.magento.com/guides/v2.3/mrg/indexing.html)

### Data migration

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

#### Migration of attributes with range

Each update attribute that contains a time range is synchronized with dates of 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](http://devdocs.magento.com/guides/v2.3/install-gde/install/cli/install-cli-subcommands-enable.html).

## Extensibility

Extension developers can interact with the Magento_ConfigurableProductStaging module. For more information about the Magento extension mechanism, see [Magento plug-ins](http://devdocs.magento.com/guides/v2.3/extension-dev-guide/plugins.html).

[The Magento dependency injection mechanism](http://devdocs.magento.com/guides/v2.3/extension-dev-guide/depend-inj.html) 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](http://devdocs.magento.com/guides/v2.3/frontend-dev-guide/layouts/layout-overview.html).

### 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](http://devdocs.magento.com/guides/v2.3/ui_comp_guide/bk-ui_comps.html).

## Additional information

For information about significant changes in patch releases, see [2.3.x Release information](http://devdocs.magento.com/guides/v2.3/release-notes/bk-release-notes.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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment