<!-- # Purpose

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

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

Standard Template: usage guidelines

 We have a , but ideally each writer will work with their dev team to review, and if needed to modify and perfect the READMEs used by their dev teams.

# Why do you need to follow a template

Each README.md will be published in Module Reference Guide (MRG) [http://devdocs.magento.com/guides/v2.1/mrg/intro.html](http://devdocs.magento.com/guides/v2.1/mrg/intro.html) without changes. Devdocs team uses markdown based software to generate the devodcs site, that is why special formatting must be followed (headings, lists etc).

# General principles

Each Magento module must contain README.md.

Each README must follow formatting described in this article.

Each README must contain informational structure described in this article.

The team responsible for a module is also responsible for the module README. Devdocs team always open for any questions about format, review, information architecture.

Use examples from [Module reference Guides](http://devdocs.magento.com/guides/v2.1/mrg/ee/BundleStaging.html).

Be sure that you use corresponding version of documentation in your devdocs links: 2.0 documentation for 2.0 READMEs, 2.1 documentation for 2.1 READMEs. -->

# 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.1/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.1/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.1/extension-dev-guide/plugins.html).

[The Magento dependency injection mechanism](http://devdocs.magento.com/guides/v2.1/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.1/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.1/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.1/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.1/mrg/ce/Sales/services.html)
 
For information about a public API in Magento 2, see [Public interfaces & APIs](http://devdocs.magento.com/guides/v2.1/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.1/mrg/ee/Staging.html#additional-information](http://devdocs.magento.com/guides/v2.1/mrg/ee/Staging.html#additional-information) for more complex example.

```
## Additional information

For information about significant changes in patch releases, see [2.1.x Release information](http://devdocs.magento.com/guides/v2.1/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.1/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.1/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.1/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.1/extension-dev-guide/plugins.html).

[The Magento dependency injection mechanism](http://devdocs.magento.com/guides/v2.1/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.1/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.1/ui_comp_guide/bk-ui_comps.html).

## Additional information

For information about significant changes in patch releases, see [2.1.x Release information](http://devdocs.magento.com/guides/v2.1/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.
```