Today, I want to shed light on the questions: how do you actually make a contribution to Magento 2? And: why does it sometimes take a bit longer to get pull requests (PRs) merged?
Major parts of this have been documented in the great DevDocs and blog posts before. Still, my work as a Magento 2 GitHub Maintainer showed that it might be helpful to write down a few words and put together some links to get started.
Table of contents
Why should I create pull requests in the first place?
Besides the obvious fame when you can call yourself a core code contributor ;-), there are some more reasons why you should consider contributing:
- working on PRs will help you to learn what it takes to write high-quality, stable core code. Transfer the quality and stability checks from the core to your daily work. This will greatly improve your work.
- when a fix or improvement becomes part of the core, you save time because you don’t have to maintain the modifications in your projects anymore.
- improving Magento as a product doesn’t only help Magento Inc. Tt also helps your clients and you who works with this software everyday. It should be in your interest that the software (into which you put hundreds and thousands of hours to become the specialist you are today) succeeds and enjoys a long life.
The 2.2.x releases are the first fruits we reaped from the lot of work that
- the community in the form of pull requests and
- the Community Engineering Team (CET) in the form of process improvements and added resources
put into these releases. (Of course, we had pull requests before, but the whole workflow and improvements got onto another level with these releases IMHO.)
How do I find something that is pull request worthy?
Basically, everything is worth a pull request. You don’t have to reinvent Magento. Small fixes of annoying bugs or even spelling improvements and small refactorings help all of us working with this system.
Having said that: if you don’t have a piece of code yet in front of you that you want to improve, you could have a look at the open issues and the Community Backlog or jump onto one of the community projects. There even is a Slack channel where you can meet Magento employees and other community members to discuss issues. Just send a mail to engcom [at] magento.com and ask for an invitation to Slack.
How do I create pull requests for Magento 2?
The basic workings are explained very well in the Code Contributions chapter of the official documentation. It tells you ybout the necessary steps and what you have to take care of when creating a PR. For example, you’ll see that code quality and automated tests are an important topic. Also, you should proceed differently based on whether you are creating new features or introduce smaller or bigger changes.
In addition, watch out for the Magento Community Engineering YouTube channel where additional tips like „Keeping your Magento 2 fork up to date“ are shared. Last, keep an eye on Contribution Days which are organised around the world and where you can write your first lines together with Magento employees.
What about the branches in the Git repository?
Well, let’s get started with the first topic which may not be totally obvious since it isn’t discussed in broad detail on the web. It revolves around the questions: why are there different branches, for which branch should I create a PR and when will my fix be released?
Let’s have a look at the official GitHub repository.
At the time of writing, „2.2-develop“ is the default branch that is displayed when you didn’t choose otherwise. That means that as of now, the 2.2 branch is the mainline. The last version released is 2.2.2 so you can guess that 2.2.x is where the main effort goes for existing code. Of course, there is a lot of working being done for the 2.3 release that’s planned to arrive later this year but when it comes to community contributions, Magento is happy to bring fixes and improvements to the current branch as much as possible.
Next, if you open the branch dropdown you will see different branches:
„2.0“, „2.1“ and „2.2“ shouldn’t need further explanation: they represent the latest release of the given branch.
„2.1-develop“, „2.2-develop“ and „2.3-develop“ show that these branches are still in development and will receive updates. I’m sure you noticed that „2.0-develop“ is missing. That’s because the 2.0.x release line has reached its end of life (if you speak German, see Wie lange werden Magento-2-Versionen unterstützt for more information). Let’s have a closer look at the existing branches
Role of the „-develop“ branches in Magento 2 contributions
The first thing to know is that you can provide a bugfix for all minor version release lines with a „-develop“ branch. It’s preferable that you create pull requests against the „default“ branch first. At the moment, that’s „2.2-develop“. This is desirable since it’s the fastest way to let merchants on the current release profit from improvements.
Sometimes, this may not be needed because the bug has already been fixed in the default branch (2.2-develop). Then, you could do a backport to 2.1-develop so that users of the older version benefit.
Sometimes, it may not be possible to provide a bugfix for the default branch because the changes violate the rules for backward compatible development. We all know the pain that patch releases could cause when things break unexpectedly, right? To let this become a thing of the past, the backward compatibility rules have been introduced. They aim to help break as little existing code as possible within a patch release. The trade-off for stability in patch releases is that some fixes cannot make it into existing minor versions.
This brings us to forward ports. While the main community effort is on 2.2, there are changes which only can be implemented in a new minor version which will be 2.3 because of these backward compatibility breaks. (Don’t be confused: often, also ports of existing patches to 2.3 are called „backports“.) While this means that it takes longer until you will see your fix in a stable release this also allows freedom to implement bigger refactorings and better solutions.
The core team plans to port all 2.2 patches to 2.3 which are not forward ported by the community itself. If possible, it’s awesome if you do the forward port yourself. It’s a tremendous task for the core team to port this vast array of pull requests, making sure nothing gets lost and everything still works as intended.
Find more information on back- and forward porting pull requests in this wiki entry.
OK, I created a PR. And now?
First: thanks for improving Magento. This is awesome!
Now the time has come where we have to do our work. Processing the pull requests. „We“, that’s the Community Engineering Team (CET) or one of the GitHub Maintainers. I’ll be honest: sometimes, PR creators have to show more patience than we’d like them to have to.
On one side, we try to process pull requests as fast as possible. On the other side, we have to make sure that the fixes work as expected without side effects. Otherwise, a new release introduces new instabilities. That’s something which nobody wants.
In addition to processing an amazing amount of pull requests, the CET manages the community projects, travels around the world to spread the world and help with contribution days. GitHub maintainers, they have their normal day jobs and then try to find set time aside to review your contributions in their free time. I don’t always manage to do that. Sorry to everybody who had to wait for a response for a longer time! 🙂
But now, enough of lame excuses.
Code reviews
Let’s assume that somebody assigned themself to work on your PR.
Obviously, the first checks that are run against your change request are automatic tests.
Codacy makes sure your changes are compliant with the Magento coding standards. Travis CI runs the test suite against the PHP versions supported by Magento. The third check verifies that you signed the Contributor License Agreement (CLA).
Now, the person assigned to the PR becomes active. If checks fail, she/he will ask you to fix it. If everything passes, we have a look at the code ourselves.
- First, we have to make sure that the code change fixes the actual issue as described.
- Second, we have to test if the change does have any side effects.
- Third, we have to verify that your code follows the best practices. On one side is the test coverage and validity of the automated tests. On the other side, automated tests cannot catch all violations. For example, a change might work but isn’t applicable for the targeted minor version because it introduces breaking changes. Or it works but it doesn’t use a certain code design pattern that would make the change more elegant/flexible/robust.
That’s the phase when your ticket is in „Review in Progress“ on GitHub.
Extended checks
When the manual code is passed after none to several revisions, we take the code for a spin in the next round. Now, the PR gets applied and tested in an extended version of the test suite. I have a soft spot for devops and infrastructures, so I’m always in awe when I see this system get to work. The code is tested against the different editions of Magento. Also, many more tests are executed which are part of the core but not run on Travis, e.g. performance tests. Magentos team did a really impressive job here in my opinion.
If problems surface, we might contact you one more time and ask for fixes (or fix it ourselves).
After the test suite passes, there is one final round of manual QA. Usually, that’s when your PR moves to „Testing In Progress“. This the last chance to catch issues before the pull requests are finally accepted. Again, the Magento QA does a very good job in spotting errors which might have been missed before.
Pass, pass and pass!
When the pull request went through all these stages, the CET takes over and proceeds with merging your code. Now, the PR moves to „Merging in Progress“ on GitHub. In the next hours to days, you’ll see new commits being referenced on the PR Conversation page. That’s your improvement making its way into the core.
And then, you will finally see this word that you were hoping for: „merged„.
Congratulations, you are a core contributor now! Hopefully, your face will soon show up on Top Contributors page.
