Magento 2: good practice regarding custom module README.md

Question

As you may have noticed, every Magento 2 core module contains a README.md file.

Example for the Magento_Catalog module:

Magento_Catalog module functionality is represented by the following sub-systems: - Products Management. It includes CRUD operation of product, product media, product attributes, etc... - Category Management. It includes CRUD operation of category, category attributes

Catalog module provides mechanism for creating new product type in the system. Catalog module provides API filtering that allows to limit product selection with advanced filters.

In order to follow good practices, I want to add a README.md to my custom module folder.

However, I'm not sure what should I write there ?

• only a small description of the module
• documentation
• release notes
• support links ?

What is or what could be the good practice regarding 3rd party modules README.md ?

Answer 1

Raphael, thanks for asking this question! (and thanks Rakesh for your solid answer.) On the Magento Devdocs team, we have a basic template for the core modules. In addition to the excellent suggestions by Rakesh above (yes, tests, please!), we like to see the following sections:

• implementation details: why and how to use the module, preferably with some example scenarios

• any dependencies (usually other modules but could be any important dependencies, libraries, etc)

• extension points, APIs, plug-ins, etc

• any introduced events

Basically, think like a user of your module; what do they need to know?

Answer 2

README.md file is used basically display overview of your module / summary of your module.

• Contents

  • Synopsis
  • Overview
  • Install the module
  • Add and register the command
  • Tests
  • Contributors
  • License

You can define your module related data in above syntamatix order given by magento core team. Just basic info in each point as declared in above.

Above each point is not mandatory to define in readme.md file whichever required is depends on your module.