Contribute to Magento 2 code

This contribution model allows contributors to maintain their own copy of the forked codebase (which can be easily synced with the main copy). The forked repository is then used to submit a request to the base repository to pull a set of changes (hence the phrase pull request).

Contributions can take the form of new components or features, changes to existing features, tests, documentation (such as developer guides, user guides, examples, or specifications), bug fixes, optimizations, or just good suggestions. We recommend also creating back-ports and up-ports as needed with your pull requests if the issue occurs in higher or lower line releases.

The Community Engineering Team reviews all issues and contributions submitted by the community developers. During the review we might require clarifications from the contributor. If there is no response from the contributor in two weeks (14 days) time, the issue is closed.

Often when the Community Engineering Team works on reviewing the suggested changes, we will add a label to the issue to indicate certain information, like the status or who is working the issue. If you’re ever curious what the different labels mean, see the table below for an explanation of each one.

Please refer to Magento Contributor Agreement for detailed information about the License Agreement. All contributors are required to submit a click-through form to agree to the terms.

GitHub and Two-Factor Authentication

When setting up access and tokens for Magento GitHub repositories, we recommend adding Two-Factor Authentication (2FA) to enhance security. Magento requires all Partners who contribute code to enable Two-Factor Authentication (2FA) on their accounts. You can use a mobile device or 2FA application for added protection.

2FA adds an additional layer of security beyond just a username/password when you access GitHub. With 2FA enabled, you log into a service with your credentials then complete an additional step providing a 2FA code. This second form of authentication helps us ensure that a malicious user will not be able to gain access to your GitHub account or any private Magento GitHub repositories.

Questions or enhancement requests?

We use this repository (the Magento 2 GitHub repository) to capture code and documentation issues. We recommend that you post all questions to a question-and-answer site, such as Stack Exchange and the Magento Forums, where Magento community members can quickly provide recommendations and advice.

Accepted pull requests and ported code

Please review the following supported and accepted pull request rules. We defined these rules to simplify and accelerate your submissions, follow code consistency, manage current and backlog tasks, and so on.

Fix for Existing Issue

Test Coverage

Refactoring

New Feature

Code Cleanup

2.1

2.2

2.3

Contribution requirements

Refer to the Magento development team’s Definition of Done. We use these guidelines internally to ensure that we deliver well-tested, well-documented, and solid code. We encourage you to use this as well!

Pull requests (PRs) must be accompanied by a meaningful description of their purpose. Comprehensive descriptions increase the chances that a pull request is merged quickly and without additional clarification requests.

Commits must be accompanied by meaningful commit messages.

PRs that include bug fixes must be accompanied by a step-by-step description of how to reproduce the bug.

PRs that include new logic or new features must be submitted along with:

Unit/integration test coverage (we will be releasing more information about writing test coverage in the near future).

Update the fork with the latest changes

As community and Magento writers’ changes are merged to the repository, your fork becomes outdated and pull requests might result in conflicts. To see if your fork is outdated, open the fork page in GitHub and if a This branch is NUMBER commits behind magento:2.2-develop. message is displayed at the top of the page. If so, your fork must be updated.

There are two ways to update your fork. The typical way is discussed in GitHub documentation. Make sure to update from the correct branch!

You can also use the GitHub interface to update forks, referred to as a reverse pull request. Though this method does have a downside: it inserts unnecessary information into your fork commit history.

On your fork GitHub page, click New pull request. You should see the following message:

There isn’t anything to compare.
magento:2.2-develop is up to date with all commits from <your fork>:2.2-develop. Try switching the base for your comparison.

Click the base link and then click Create pull request.

Provide a descriptive name for your pull request in the provided field.

Scroll to the bottom of the page and click Merge pull request, then click Confirm Merge.

Check out this video to see the process in action:

Create a pull request

First, check the existing PRs and make sure you are not duplicating others’ work.

To create a pull request:

Create a feature branch for your changes and push those changes to the copy of your repository on GitHub. This is the best way to organize and even update your PR.

In your repository, click Pull requests on the right, and then click New pull request.

Ensure that you are creating a PR to the one of following branches: magento:2.3-develop, magento:2.2-develop or magento:2.1-develop branch. We accept PRs to these branches only.

Review the changes, then click Create pull request. Fill out the form, and click Create pull request again to submit the PR—that’s it!

After submitting your PR, you can head over to the Magento 2 repository’s Pull Requests panel to see your PR. Your PR undergoes automated testing, and if it passes, the Community Engineering Team considers it for inclusion in the Magento 2 core. If some tests fail, please make the corresponding corrections in your code.

Porting code contributions across Magento versions

In order to keep consistency between Magento release lines (2.1, 2.2, 2.3, etc), there are two techniques of code delivery: back-port and/or up-port. Every Magento Contributor, who wants to deliver their solution across all Magento versions, faces the same problem. How do you port fixes easily?

We provide two options to create back-ports and up-ports for your code contributions:

Creating back-ports and up-ports are recommended and a best practice, but not required to contribute code. Anyone can create a back-port and up-port for an already merged pull request.

What are up-ports and back-ports?

As a best practice, we recommend creating back-ports and up-ports for your code contributions.

Back-ports (or Backports) contribute your code and fixes to a lower release line. You want to create a back-port if the issue exists in a lower release line. If you fixed an issue in a release line and there is a supported lower version, create a pull request to that lower release line to address the issue. For example, you may have contributed a fix to 2.3 and back-port to 2.2 and 2.1.

Up-ports (or Forwardports) contribute your code and fixes to a higher release line. You want to create an up-port if the issue exists in a higher release line. If you have an issue fixed in a non-latest release line, create a pull request to the latest branch in order to address that issue in an upcoming minor release. For example, you may have contributed a fix to 2.1 and up-port to 2.2 and 2.3. We recommend contributors create an up-port for every pull request delivered to a lower release line.

Magento Porting Tool

This tool ports fixes automatically across versions with a few simple steps. It allows you to create ports only for merged pull requests.

Access the tool at porting.engcom.dev.magento.com. The first time you visit, you need to login and authorize with GitHub credentials. The tool performs all actions using your token.

Check the documentation to make sure the behavior you are reporting is really a bug, not a feature.

Check the existing issues to make sure you are not duplicating somebody’s work.

To add an issue:

In the Magento 2 public repository, click the Issues link on the right.

Click New issue.

Fill in the Title and Issue description.

Click Submit new issue.

Help triage issues {#triage}

In addition to contributing code, you can help to triage issues. This can include reproducing bug reports or asking for vital information, such as affected versions or instructions to reproduce bugs. If you would like to start triaging issues, one easy way to get started is to subscribe to Magento on CodeTriage.

Labels applied by the Magento team

Refer to the following table for a description of each label. These labels are applied by the Magento development team to community contributed issues and pull requests, to communicate status, impact, or which team is working on it.

Label image

Description

Pull Request Resolution Status

The pull request has been accepted and will be merged into mainline code.

The pull request has been rejected and will not be merged into mainline code. Possible reasons can include but are not limited to: issue has already been fixed in another code contribution, or there is an issue with the code contribution.

The Community Engineering Team needs additional information from the reporter to properly prioritize and process the pull request.