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 ?

2 Answers 2


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?

  • 1
    Thanks for that. Are you part of the Magento devdocs team ? Commented May 23, 2016 at 15:55
  • 3
    HI, Yes, and getting better readmes in the world is a passion of the entire DevDocs team. ;-)
    – tanberry
    Commented May 23, 2016 at 15:58

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.