Christmas is the time of giving and mince pies, but since I am in Germany and cannot get mincemeat let’s focus on the giving. In this case I will be looking at giving from the point of view of open source contributions. More specifically, pull requests to the Magento 2 project.
Let’s say you are working on a Magento project, and you find a bug. That’s bad. Before February 2017 and the creation of the Community Engineering Team, you would create your own bug fix module and the story would end there, but now the story can continue.
In this blog I would like to talk you through the pull request process at Magento and give you some tips on how to make the process as easy as possible.
Preparation
For this article I will assume you have a github account, a fork of the Magento 2 Project and a fix to provide. The first step in the process would be creating a topic branch locally, rather than working directly on one of the develop branches, commit your changes to this branch, and finally push when you are ready to give your pull request.
Creating your Pull Request
To create your pull request, navigate to the Magento 2 github page and find and select the “New pull request.” button. On this page you can select “compare across forks” and then will be able to select the “base fork” and “base branch”, in this case the fork should be “magento/magento2” and in most cases the branch should be the projects defined main branch, at time of writing this was 2.2-develop, but you can provide a pull request to any appropriate branch. For the “head fork” and “compare branch” you should select your fork and topic branch. At this stage you should see a form to add a title and description to your pull request and below that a list of all the commits you wish to provide.
As part of the Magento project we have provided a pull request template , and for most cases we request the following:
- Meaningful description of the pull request,
- Link to any related/fixed issues on github,
- Manual testing scenario,
One of the keys here to help with the pull request is providing a meaningful description of what you have changed and why, along with at least 1 manual testing scenario. This will help the team reviewing this pull request to decide if the solution is valid.
For more general information on creating a pull request, you can see the github help pages.
Processing the pull request
Once you have created the pull request two things will happen. First, a travis build will be run automatically, and second, at least one member of the Community Engineering team or community maintainers will pick up your review. They will be your main point of contact during the processing of your pull request. The job of the reviewer here is to make sure that the code you have provided aligns with the coding standards, provides a meaningful addition to the system, and does not break another feature.
During the review of the pull request your code will be run in an open source (previously known as community edition), commerce (previously enterprise), and a B2B build. These builds will help the reviewer make sure that the code has no negative effects, either bug or performance wise.
After the reviewer has checked that these code changes make sense to be merged, match our standards, and all the tests are passing, your review will then be passed onto the quality assurance team. This team will run the test cases you have provided with your pull request, plus other test cases related to this section of the system to validate your changes.
After these steps your pull request will then be ready to be merged into the branch defined in your pull request and you will now be a contributor to the Magento 2 project.
Final thoughts
We do try to keep the time from pull request created to final approval and merge as short as possible, but some pull requests do take longer than others. We also aim to keep you informed throughout the process as much as possible and to include you in any architectural discussions related to your pull request.
I hope this has helped you gain more insight into our processes and I will leave you with some final thoughts.
- It is a nice idea to setup your fork with travis so that you can see any test failures before creating your pull request (https://docs.travis-ci.com/user/getting-started/#To-get-started-with-Travis-CI)
- I highly recommend that when picking a contribution, you choose something you have passion for,
- Communication is key. We aim to keep you updated with review feedback, test failures, and other items with regards to this pull request. This communication should be two way, so feel free to ask questions via github or join our slack channel (send request to join to engcom@magento.com)
- Please also review our dev docs on contribution (http://devdocs.magento.com/guides/v2.2/contributor-guide/contributing.html)
Have fun!