Magento 2 separates code to public and private. The public codebase is marked with the @api annotation. According to Semantic Versioning, backward compatibility communication is promised only for public code.
The recently released Magento 2.2 software includes significantly increased @api annotation coverage. All blocks used in layout instructions, abstract classes, and other important APIs were marked. \Magento\Framework\View\Element\Template is an example of an important class marked with @api.
As a result, the public API surface of PHP code has increased by a factor of 4 and private code usage in core modules has decreased by approximately 86%. In total, about 23% of Magento 2.2 PHP APIs are public. It means that third-party developers will be better informed about breaking changes in future releases.
We also significantly expanded our API stability policy to non-PHP public code. Our Versioning document describes in details what API change communication promises we make for PHP & JS code, XML configuration, templates, and database schema.
Please check out the new @api coverage in our latest codebase on Github and review the Versioning document. Your feedback is always welcome.
