Code contributions

data-variant=info 
data-slots=text
Connect with Magento Open Source Contributors and Maintainers to learn more about contributions and special projects. Join us in our Slack workspace, in the #general channel, follow the #announcements, and browse for more channels!

Contribute to Magento Open Source code

We use the fork and pull model to contribute to the Magento Open Source codebase. This method 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 pull request to the base repository to merge a set of changes from the fork into the main repository.

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.

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 4 weeks (28 days) time, the issue might be closed.

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. See Labels to learn more.

data-variant=info 
data-slots=text
Refer to the Adobe Contributor Agreement for detailed information about the License Agreement. All contributors are required to submit a click-through form to agree to the terms.

Community backlog priority

In order to provide timely resolution on the most critical issues and pull requests, the Adobe team has implemented Severity/Priority concepts to our community driven projects. This approach makes open-source collaboration more transparent for all participants. Having clear contribution rules in place helps to build clear expectations for Community Contributors and establish clear priorities for Community Maintainers and the Adobe team.

If you would like to contribute improvements or bug fixes and make sure it is valuable for the Community as well, we highly recommend that Community Contributors to take issues from the backlog based on Priority. Adobe and Community Maintainers process contributions based on the issue/pull requests priority starting from P0, P1 to P4.

data-variant=info 
data-slots=text
Priority signifies how important or detrimental a defect is. The defect priority status is set by Product Managers. Priority also helps to determine the scheduling of the fix: Higher priority bugs will be fixed and merged first. It is a reflection on how bad the bug is for the system and also for business or marketing requirements.
data-variant=info 
data-slots=text
Severity is a measure of how 'bad' the bug is and how much disruption it causes, without regard to remaining work or the release schedule.

Priority and severity descriptions

Severity
Description
Severity: S0
- Affects critical data or functionality and leaves users with no workaround.<br/>- Significant catastrophic impact.<br/>- A problem that is blocking the ability to work. An immediate fix is needed.<br/>
Severity: S1
- Affects critical data or functionality and forces users to employ a workaround.<br/>- Impact to the key product qualities.<br/>- An immediate fix is needed.<br/>
Severity: S2
- Affects non-critical data or functionality and forces users to employ a workaround.<br/>- Impact to the product qualities that makes the product more usable.<br/>- Major restrictions or short-term circumventions are required until a fix is available. A fix is important.<br/>
Severity: S3
- Affects non-critical data or functionality and does not force users to employ a workaround.<br/>- Problem has moderate impact requiring some restrictions. The fix is in an area that is not critical.<br/>
Severity: S4
- A minor problem, annoyance, or technical issue with minimal impact.<br/>- Impact that does not prevent or hinder functionality.<br/>- Affects aesthetics, professional look and feel, "quality" or "usability".<br/>
Priority
Description
Priority: P0
- The defect needs to be fixed right now, everything else can wait.<br/> - This generally occurs in cases when the entire functionality is blocked.
Priority: P1
- Needs to be fixed before any other issues.<br/>- Once P0 defects have been fixed, a defect having this priority is the next candidate for fixing.
Priority: P2
- Should be fixed as early as possible<br/>- A defect with this priority could have functionality issues which are not to expectations.
Priority: P3
- May be fixed according to the position in the backlog.
Priority: P4
- No current plan to fix. Fixing can be deferred as a logical part of more important work.

Who and how can define severity and priority?

Priority

The Adobe team defines priorities during regular triage review meetings, based on the community assessment for severity. Community members can participate in triaging issues and PRs by joining the scheduled meeting held every Tuesday from 11:00 to 12:00 UTC.

Severity

The following list consists of questions you can ask to help determine the proper severity:

The number of 'Yes' answers should help you to determine the severity.

GitHub and two-factor authentication

Adobe requires all Partners who contribute code to enable 2FA on their GitHub accounts. You can use a mobile device or 2FA application for added protection. See Configuring two-factor authentication in the GitHub help.

We also recommend creating a personal access token for your account to use when interacting with GitHub in scripts and on the command line. See Creating a personal access token for the command line in the GitHub help.

Questions or enhancement requests?

We capture code-related issues in the GitHub repo and documentation-related issues in the Commerce Docs - Issues Project Board. If you have questions about functionality or processes, we recommend posting them to a question-and-answer site, such as Stack Exchange and the Community Forums, where Magento Open Source community members can quickly provide recommendations and advice.

Submit feature requests or enhancement suggestions to the Community Forums. For details about how requests are managed, see Improvements to GitHub Management.

Accepted pull requests and ported code

data-variant=help 
data-slots=text
v2.4 Contribution Notice: Adobe is focusing development efforts on v2.4, so we are no longer accepting pull requests to the v2.3, v2.2, v2.1, and v2.0 release lines.

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

Fix for Existing Issue
Test Coverage
Refactoring
New Feature
Code Cleanup
2.1
No
No
No
No
No
2.2
No
No
No
No
No
2.3
No
No
No
No
No
2.4
Yes
Yes
Yes
Yes
Yes

Contribution requirements

  1. Contributions must adhere to the coding standards.

  2. Refer to the 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!

  3. 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.

  4. Commits must be accompanied by meaningful commit messages.

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

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

  7. For large features or changes, open an issue to discuss your proposal first. Notifying us in advance can prevent duplicate or unnecessary effort, and also offers an opportunity to get additional background information and help from other contributors.

  8. To report a bug, open an issue and follow the Issue reporting guidelines.

  9. Verify that all automated tests on your pull request pass successfully.

Forks and pull requests

For complete information about contributing to Magento Open Source projects, see the Beginner Guides on the GitHub repository. These guides help you:

Squash commits

Sometimes your pull request may have more than one commit (the main commit, then changes to it after review, etc). A good practice is to deliver commits that bring finalized, functional parts/bugfixes. In that case, all intermediate commits like "static test fix", "typo fix", "minor refactoring" should be squashed into a single commit. This helps keep a clean history and makes the repo easier to read. There is no requirement to have only one commit per PR. However, the intermediate commits in most cases bring no value into the commits history, which is why it is a good to keep the history clean and useful.

Contributor assistant

The Contributor Assistant is a bot that runs on all repositories in the magento GitHub organization. It helps automate issue and pull request workflows by using commands entered as comments.

Assigning an issue

If you would like to have an issue assigned to you, add a comment and the contribution assistant will do the work.

Command: To assign as issue to your GitHub account, add the following command as a comment to the issue:

@magento I am working on this

This command has several variations:

@magento I am working on this @magento I am working on it @magento I'm working on this @magento I'm working on it

Actions: The following actions occur:

Permissions:

Report an issue

To maintain an effective bug fix workflow, we ask reporters to follow some simple guidelines.

Before creating an issue, do the following:

If you are sure that the problem you are experiencing is a bug, file a new issue in GitHub following the recommendations below.

Issue template

The Issue Reporting Template is a default placeholder for every new issue. Follow the sections carefully, as it ensures it will pass Gate 1 quickly.

data-variant=info 
data-slots=text
Note that a higher level of detail in the report increases the chance that someone will be able to reproduce the issue.

Title

The title is a vital part of the bug report. A well written title should contain a clear, brief explanation of the issue, emphasizing the most important points.

A good example:

"Unable to place order with Virtual product and PayPal."

An unclear example:

"Can't checkout."

Issue description

Preconditions

Stating preconditions is very important. Provide information on:

Example:

  1. Magento Open Source 2.0.0 without sample data is installed.
  2. PayPal payment method is set up.
  3. Test category is set up.
  4. Virtual Product is created and assigned to the Test Category.

Steps to reproduce

Good steps to reproduce are vital to a good bug report. The issue is more likely to be fixed if it can be reproduced.

Precisely describe each step required to reproduce the issue. Try to include as much information as possible; even minor details could be crucial.

Example:

  1. Navigate to storefront as a guest.
  2. Open Test Category.
  3. Click "Add to Cart" on the Virtual Product.
  4. Open mini shopping cart and click "Proceed to Checkout".

Actual and expected result

To ensure that everybody involved in the fix understands the issue, precisely describe the result you expected to get and the result you actually observed after performing the steps.

Expected result:

Order is placed successfully, customer is redirected to the success page.

Actual result:

"Place order" button is not visible, order cannot be placed.

Additional information

Additional information is often requested when the bug report is processed. You can save time by providing both Magento Open Source and browser logs, screenshots, repository branch and HEAD commit you checked out to install Magento Open Source and any other artifacts related to the issue.

Help triage issues

In addition to contributing code, you can help triage issues. This can include reproducing bug reports or asking for vital information, such as affected versions or instructions to reproduce bugs. If you want to triage issues, you can start by subscribing to Magento on CodeTriage.

Labels applied by the Community Engineering team

We apply labels to public pull requests and issues to help other participants retrieve additional information about current progress, component assignments, Magento Open Source release lines, and much more. The following information details global labels used in Magento Open Source repositories and across Community Engineering contributions.

Release Lines

Release line labels indicate the specific release lines affected by the issue or PR. For example, if working on a fix for 2.4.0 you would apply the Release Line: 2.4. This effectively includes all releases in this line.

Progress

Progress labels indicate the Pull Request status on each review stage:

Partners

All partners Pull Requests should be marked with label partners-contribution. Additionally, add a partner label for PRs submitted by specific Partners. Use the format: Partner: <PartnerName>. The following are Partner examples:

Example labels:

Components

Component labels indicate the components affected by the Pull Request. To learn more about available components and assigned architects, see Components Assignment.

Example labels:

For edge cases, Component: Other and Component: Multiple may be used.

Events

Event labels mark recommended issues and submitted PRs for a specific event. Events may include Contribution Days, Hackathons, Imagine, special events like Smashtoberfest, and others. Contributors and Maintainers can easily locate code when attending those events. Some events may also have a Community Engineering Slack channel using the same label.

Example labels:

General

General labels include a variety of tasks and definitions for pull requests and issues.

Issue resolution status

Labels applied to issues through verification and completion. For details on the process, see GitHub Issues Processing Workflow.