Magento Forums
Help
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

Magento 2 Technical Guidelines

Anton_Kril
Adobe Team
Adobe Team
‎03-31-2017 09:44 AM
‎03-31-2017 09:44 AM

Today we published version 1 of our technical guidelines. This document contains a list of simple coding and application design truths that all Magento 2 developer team members agree to. It describes the desired state of the Magento 2 codebase.

 

The document is used by core developers as a reference during code reviews. Some rules have corresponding code checks in Magento static tests.

 

Please note, that not all Magento 2 code adheres to these rules. Different rules were established at different points in time, and older code does not (yet) follow the newer rules. However, we require all new code to be written with all current rules and best practices in mind.

 

By publishing these guidelines, we are sharing our vision of good code and application design with you. Understanding this vision will help community developers to better understand the changes we make in the code, and how Magento will evolve.

 

We encourage community developers to follow these guidelines to write better code that make development with Magento more convenient.

 

More guidelines will be published incrementally. We will announce any significant improvements to the guidelines here on the developer blog, otherwise feel free to check back periodically for additional content.

4 Comments
alanstorm
Occasional Contributor
‎03-31-2017 03:17 PM
‎03-31-2017 03:17 PM

Per those guidelines 

 

8.5. Only the @api code of any module can be referenced by other modules.

 

As of today, if third party developers follow this guideline, the extensions they produce will be unable to do anything useful in the Magento system. That is because an overwhelming majority of methods are not marked with @api.

 

Can you advise how a third party developer can proceed on their projects and still follow this guideline?

 

If the above advice to to hold tight, ignore the guideline for now, and wait for a future release of Magento 2, can you please advise on which other guidelines can be similarly ignored for the time being?

 

Thank you!

akent99
Regular Contributor
‎03-31-2017 03:23 PM
‎03-31-2017 03:23 PM

Two strategies here:

  • We are putting a lot more @api annotations into 2.2. They should be hitting the repo soon. When they do we want to encourage extension developers to see if we have all they need.
  • Consider going through your code and creating a pull request to add @api annotations to the core. We can then review actual real usages of APIs.

But there will be misses in APIs in 2.2 still. It may take a few releases to get the coverage correct. The more coverage we can get however, the closer we are to the SemVer dream. This document is a statement of where we want to get to so everyone knows the direction we are heading.

 

alanstorm
Occasional Contributor
‎04-05-2017 05:12 PM
‎04-05-2017 05:12 PM

I'm really not sure what to make of that response @akent99. I'm operating from the assumption that semantic-versioning/the-@api-methods are there to inform third party developers which methods are stable to use.

However, your response indicates this isn't the case, won't be the case possibly for years to come, and that you're actually looking to the third party extension developers to define which methods they need, and then -- maybe? -- you'll add @api to them? It's a very confusing and weird response -- even more so since this isn't the first time the idea of using third party developers to map out @api methods (in the next version -- we swear) has come up.

 

It's hard to come away from this exchange and think that third party developers (extension developers or system integrators) have any guarantees about what will or won't be supported from version to version in Magento 2. Said another way, the message seems to be third party developers need to accept that our extensions will break from version to version and either bring down systems with them, or block potential upgrades if we're lucky enough to have our code running on the handful of systems that have fully embraced composer.  It makes the inclusion of "only use api annoted methods" seem like guidelines theatre, and raises questions about which other guidelines are similarly paper tigers. 

 

Maybe that's just the state of the world these days, but it doesn't make for exciting feelings about the state of the independent, open source Magento 2 platform/programmer-community.

akent99
Regular Contributor
‎04-05-2017 08:52 PM
‎04-05-2017 08:52 PM

Hi Alan, sorry I was unclear. I will try to reword.

  • @api annotations *are* for semantic versioning. (There is no change here.)
  • 2.2 will have more @api annotations included than 2.1 - these will be in GitHub before 2.2 is released.
  • We also welcome community suggestions for other APIs they would like to have an @api annotation added. They don't have to, but they are welcome to if it will help their particular extension.
  • We are going to continue to work on additional APIs over coming releases.

 

You are correct in that we do not guarantee that zero backwards incompatible changes will be made across all modules between releases, as per all software products. Our public commitment is (1) to minimize backwards incompatible changes between releases, and (2) when they are needed, to communicate backwards incompatible changes via SemVer for @api annoatated APIs. There are two related but separate commitments. Saying we will report changes via SemVer is not an indication that we plan to break things all the time. That does not help anyone.

 

I hope that helps clarify!