This is a beta release of documentation for Magento 2.4, published for previewing soon-to-be-released functionality. Content in this version is subject to change. Links to the v2.4 code base may not properly resolve until the code is officially released.

Code Contributions

Edit on GitHub
Log an Issue

The following topics are included in this guide:

Connect with Magento Contributors and Maintainers to learn more about Magento 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 2 code

We use the fork and pull model to contribute to the Magento 2 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 two weeks (14 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.

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.

Community Backlog Priority

In order to provide timely resolution on the most critical issues and pull requests, the Magento 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 Magento team.

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

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.

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.
- Significant catastrophic impact.
- A problem that is blocking the ability to work. An immediate fix is needed.
Severity: S1 - Affects critical data or functionality and forces users to employ a workaround.
- Impact to the key product qualities.
- An immediate fix is needed.
Severity: S2 - Affects non-critical data or functionality and forces users to employ a workaround.
- Impact to the product qualities that makes the product more usable.
- Major restrictions or short-term circumventions are required until a fix is available. A fix is important.
Severity: S3 - Affects non-critical data or functionality and does not force users to employ a workaround.
- Problem has moderate impact requiring some restrictions. The fix is in an area that is not critical.
Severity: S4 - A minor problem, annoyance, or technical issue with minimal impact.
- Impact that does not prevent or hinder functionality.
- Affects aesthetics, professional look and feel, “quality” or “usability”.
Priority Description
Priority: P0 - The defect needs to be fixed right now, everything else can wait.
- This generally occurs in cases when the entire functionality is blocked.
Priority: P1 - Needs to be fixed before any other issues.
- 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
- 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 Magento team defines priorities during regular triage review meetings, based on the community assessment for severity.

Severity

  • Community Maintainers are allowed to set Severity labels during the initial issue triage according to the Issue Processing Workflow.
  • The Magento team can set or edit severity and priority based on our internal triage process and information provided in the initial community triage.
  • Issue reporters can provide their own evaluation for severity by selecting a checkbox in the Issue description.

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

  • Does the system stop working after defect occurs?
  • Can the system recover from the defect?
  • If the defect is recoverable, does the system require external effort to recover from the defect? (i.e. it will not recover on its own)
  • Does the defect affect other related sections (or the entire system)?
  • Can I repeat the defect in some other system having same configuration (O/S, Browsers) as that of the system where I found the defect?
  • Does the defect show up in other configurations?
  • Does the defect affect all users/roles? (i.e. Only a particular category of users will face the defect)
  • Does the defect occurs frequently?
  • Are the inputs to make the defect easy to reproduce? (i.e. special data is not required)

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

GitHub and Two-Factor authentication

Magento 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 the Magento 2 repo and documentation-related issues in the Magento DevDocs repo. If you have questions about Magento functionality or processes, we recommend posting them to a question-and-answer site, such as Stack Exchange and the Magento Forums, where Magento community members can quickly provide recommendations and advice.

Submit feature requests or enhancement suggestions to the Magento 2 Feature Requests and Improvements forum. For details about how requests are managed, see Improvements to GitHub Management.

Accepted pull requests and ported code

v2.4 Contribution Notice: Magento 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 Magento coding standards.
  2. 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!
  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 projects, see the Beginner Guides on the Magento 2 repository. These guides help you:

  • Fork a repository
  • Create a branch
  • Find and work issues
  • Create tests
  • Submit a pull request

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.

Magento contributor assistant

The Magento Contributor Assistant is a bot that runs on all GitHub magento repositories. 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:

1

@magento I am working on this

This command has several variations:

1
2
3
4

@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:

  • If the user is a member of the Magento GitHub organization, the user will be assigned to the ticket automatically.
  • If the user is not yet a member of the Magento GitHub organization, an invitation will be sent to the user. Check your email or accept the Github invitation. Once the user has joined the Magento GitHub organization, the user should repeat the command to get assigned to the ticket.

Permissions:

  • All permissions granted for all users.

Currently, the Magento Contributor Assistant automatically deploys a test instance based on a contributor’s pull request, or, it provides a vanilla Magento instance on the magento/magento2 repository. This is used to test pull requests or reported issues.

Deploy vanilla Magento instance

When you want to verify an issue or pull request, use the instance command to generate a Magento instance. This is a clean installation of a specified version tag or branch of a specified release line.

Command: To deploy a Magento instance, add the following command as a comment to the GitHub pull request or issue:

1

@magento give me {$version} instance

For version, the currently supported values are latest version tags and the 2.4-develop branch.

Actions: The following actions complete the command:

  • If the instance does not exist, it is deployed. Deployment takes approximately 2 minutes.
  • If the instance exists, a fresh instance is redeployed.
  • By default, instances have a lifetime of 3 hours. All deployments are then terminated.

Admin access:

Admins access is shared via comment on GitHub.

Permissions:

  • All permissions granted for all users.

Deploy instance based on PR changes

To verify and test changes within a pull request, enter a command to generate a Magento instance using code based on the PR.

Command: To deploy, Community Maintainers, a Magento EngCom Team member, or a contributor under the existing Pull Request enters the following command as a comment to the pull request:

1

@magento give me test instance

Actions:

  • It deploys a new Magento instance based on Pull Request changes.
  • Deployment takes approximately 2 minutes.
  • By default, instances have a lifetime of 3 hours. All deployments are then terminated.

Admin access:

Admins access will be shared via comment on GitHub.

Permissions:

Combine multiple pull requests

To optimize the pull request queue, enter a command with a series of related pull request numbers to merge and test the code. If all tests pass, the entered PRs are merged into the current PR.

Command: To combine pull requests, a member of the Community Maintainers or Magento EngCom Team under the existing Pull Request will enter the following command:

1

@magento combine {xxx} {yyy} {zzz}

The command merges the listed related pull requests (xxx, yyy, zzz) into the current pull request. For example: @magento combine 1234 1238 1239.

actions: When all conditions are passed, all related pull requests will be closed and merged to the current PR:

  • Current pull request allows changes from maintainers.
  • All mentioned pull requests are open.
  • All mentioned pull requests have been created by the same contributor (author).
  • All mentioned pull requests have same target (base) branch.
  • All mentioned pull requests can be merged with each other.

Permissions:

Report an issue

If you find a bug in Magento 2 code, you can report it by creating an issue in the Magento 2 repository.

Before creating an issue:

  1. Read the Issue reporting guidelines to learn how to create an issue that can be processed in a timely manner.
  2. Check the documentation to make sure the behavior you are reporting is really a bug, not a feature.
  3. Review the existing issues to make sure you are not duplicating another contributor’s work.

To add an issue:

  1. In the Magento 2 public repository, click the Issues tab.

    Issues tab

  2. Click New issue.

    Create new issue

  3. Select a type of issue: Bug report, Developer experience issue, or Feature request.
  4. Fill in the Title, description, and additional information for the template.
  5. Click Submit new issue.

When you submit the issue, a validation process begins. If the issue doesn’t have enough information, you as the Reporter may need to add more information. See GitHub Issues Processing Workflow for complete details on issue verification.

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 begin 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 release lines, and much more. The following information details global labels used in Magento 2 repositories and across Community Engineering contributions.

Release Lines

Release line labels indicate the specific Magento 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.

  • Release Line: 2.3
  • Release Line: 2.4

Progress

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

  • Progress: needs update - The Community Engineering Team needs additional information from the reporter to properly prioritize and process the pull request.
  • Progress: on hold - The pull request is on hold due and will be further reviewed to accept or reject.
  • Progress: accept - The pull request has been accepted and will be merged into mainline code.
  • Progress: reject - 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.

Contribution awards

The level of investigation, research, and work required for a task may differ. Contribution Rewards labels indicate what type of contribution awards will be applied when completing an issue and PR. Some awards will provide higher points and rewards than others.

  • Award: complex
  • Award: advanced
  • Award: special achievement
  • Award: category of expertise
  • Award: test coverage
  • Award: devdocs update
  • Award: MFTF test coverage
  • Award: bug fix
  • Cleanup
  • Port

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:

  • partners-contribution
  • Partner: Atwix
  • Partner: Comwrap
  • Partner: Interactiv4
  • Partner: Wagento

Components

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

Example labels:

  • Component: Catalog
  • Component: Report
  • Component: Checkout

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:

  • Event: mm18in
  • Event: mm17es
  • Event: mlau18

General

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

  • good first issue - Indicates a good issue for first-time contributors.
  • help wanted - Indicates the creator or author needs help with a decision, advice for resolving, and so on.
  • triage wanted - Indicates the issues are under triage. See this information to learn more about the Triage Wanted program.

Issue resolution status

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

  • Issue: Format is not valid - Gate 1 failed. Automatic verification by the Automated Contributor Assistant failed and the issue needs updates. The format of the issue description and minimum required information is not provided: Preconditions, Steps to Reproduce, Actual Result, Expected Result. Previous label G1 Failed.
  • Issue: Format is valid - Gate 1 passed. Automatic verification by the Automated Contributor Assistant passed for all issue content. Previous label G1 Passed.
  • Issue: Clear Description - Gate 2 passed. The Community Engineering Team has confirmed that this issue contains the minimum required information to reproduce. Previous label G2 Passed.
  • Issue: Cannot Reproduce - Gate 3 failed. The issue could not be reproduced or validated. Previous label Cannot Reproduce.
  • Issue: Confirmed - Gate 3 passed. Manual verification of the issue description and reproduction steps was confirmed. Previous label G3 Passed.
  • Issue: Ready for Work - Gate 4 passed. The issue is acknowledged and added to the backlog for open development. Previous label acknowledged.
  • Reproduced on 2.3.x - The Community Engineering Team reproduced the issue on latest 2.3.x release.

  • Reproduced on 2.4.x - The Community Engineering Team reproduced the issue on latest 2.4.x release.

  • Fixed in 2.3.x - The issue has been fixed in one of the 2.3.x releases.
  • Fixed in 2.4.x - The issue has been fixed in one of the 2.4.x releases or in 2.4-develop branch and will be available with the upcoming patch release.
  • non-issue - A described behavior in the issue description is valid and shouldn’t be changed in Magento code base.

DevDocs

All contributions to DevDocs receive the following labels:

  • New topic- New topic submissions for content that has never existed on DevDocs such as tutorials, references, instructions, and so on
  • Major update - Significant original updates to existing content
  • Technical - Updates to the code or processes that alter the technical content of the document, such as code snippets, reference documentation, parameter names and values, and other relevant content
  • Editorial - Fixes for typos, grammatical inconsistencies, or minor rewrites to correct inaccuracies

Contribution awards and points

We are thankful for all contributions, and we always recognize our most active members. Our aim is to find and recognize our top contributors according to points awarded during a given time period (monthly/quarterly/yearly). Contributors can earn points in numerous ways with a focus on pull requests (PR) to the backlog and special projects.

The Community Engineering team assesses each PR and determines the best awards for the submitted work. Contribution points are calculated according to the assessment results. We award points when the PR is merged.

How points are awarded

Every merged PR receives one base achievement and potentially one, or more, additional achievements. These achievements are applied to PRs during review and assessment. Contributors and maintainers receive points after the PR is merged.

Due to the level of work required for developing and reviewing a PR, contributors and maintainers receive the same amount of points.

For instance, see this calculated reward points example:

  1. When a contributor submits a PR with complex code contributions, they receive a total of 30 points:
    • Improvement (base achievement) = 10 points
    • Complex (additional achievement) = 20 points
  2. When a contributor submits a PR with complex code and tests, they receive a total of 40 points:
    • Improvement (base achievement) = 10 points
    • Complex (additional achievement) = 20 points
    • Test coverage (additional achievement) = 10 points
  3. When a contributor submits a PR port of an existing merged PR, they receive a total of 35 points:
    • Improvement (base achievement) = 10 points
    • Complex (additional achievement) = 20 points
    • Author of ported issue = 5 points
  4. When a maintainer reviews and approves a PR with complex code and tests, they receive a total of 40 points:
    • Improvement (base achievement) = 10 points
    • Complex (additional achievement) = 20 points
    • Test coverage (additional achievement) = 10 points

Earned achievements display as labels in each PR in GitHub and for each contributor, partner, and maintainer on magento.com.

Multiple minor editorial fixes should be combined into a single PR, for the sake of efficiency.

Base achievements

Every merged PR receives one base achievement.

Achievement Points Description
Improvement 10 Contribution contains code improvements, refactoring, or a bug fix.
Port 5 Contribution ports an existing solution between release lines. The author of the original PR receives an additional 5 points when another person contributes the ported PR.
Code Cleanup 1 Contribution contains code cleanup, such as typos, inline documentation, coding style, remove unused code, and minor style/design fixes.

Additional achievements

Every PR may receive several additional achievements during assessment.

Achievement Points Description
Advanced 30 Contribution provides new features, such as introducing a new CLI command or integration with the new payment or shipping methods.
Complex 20 Contribution contains complete refactoring of legacy code, improvements to application design, or updates to libraries.
Special achievement 20 Contribution earns recognition in a specific category, such as for extensive tests coverage, improved framework design, improved APIs or API coverage, and improved customizability.
Test coverage 10 Contribution contains a fix or improvement and new tests or test cases.
MFTF test coverage 10 Contribution contains MFTF tests.
Bug fix 10 Contribution fixes one or more known GitHub issues.
Author of Ported Issue 5 Additional points for a contribution that ports (up port or back port) a previous PR across release lines by another contributor
Issue Triage: Confirmed 5 A public issue report is verified and confirmed. The description contains all the required information needed to easily reproduce the issue with the provided steps.
Issue Triage: Rejected/Closed 4 A public issue report is verified and closed/rejected because it is not a bug or cannot be reproduce using the provided steps in the description on the supported Magento versions.

Docs awards and points

Contributors and maintainers can also earn rewards for pull requests (PRs) that are merged in the DevDocs and MerchDocs repositories. These earned points add to contributor totals. Like code contributions, the Docs team assesses the PRs and applies labels (which may vary between repositories) to determine the level of work and achievements. Each PR receives one base achievement and potentially additional achievements.

Some documentation projects, such as MFTF and PWA, are published on the DevDocs site, but the source repositories exist outside of the DevDocs repository. The teams that maintain these projects have discretion over defining points for documentation contributions.

These examples show how reward points are calculated:

  • A contributor who submits a PR that reformats HTML into markdown or fixes typos will receive an Editorial (base achievement) label = 1 point
  • A contributor who submits a PR with a code sample update and new parameter descriptions will receive an Improvement (base achievement) label = 10 points and either a Major update (additional achievement) label = 20 points OR a Technical label (additional achievement) = 10 points

Base achievements

Every merged PR to the DevDocs repository receives one base achievement. If you enter a PR with editorial fixes and new content, you receive the Improvement and additional achievements.

Achievement Points Description
Improvement 10 Contribution contains document improvements, adding missing features of inconsistency between code base and documentation, and similar.
Editorial 1 Contribution contains fixes for typos, grammatical inconsistencies, or minor rewrites to correct inaccuracies.

Additional achievements

Each PR can earn one of the following additional achievements. If you entered an editorial PR, you may not receive an additional achievement.

Achievement Points Description
New topic 30 New topic submissions for content that has never existed in DevDocs, such as tutorials, references, instructions, and other relevant content.
Major update 20 Significant updates to existing content.
Technical 10 Updates to code or processes that alter the technical content of the document, such as code snippets, reference documentation, parameter names and values, and other relevant content.

If the PR earns recognition for significant updates and additions to the documentation, it may also receive a Special Achievement label, which garners an additional 20 points. This is determinable at the time of internal assessment. Certain issues may already be labeled as Special Achievement in an effort to prompt contribution—the PRs that fix these issues will receive the extra 20 points.

Contribution programs

Both DevDocs and MerchDocs have contribution programs for publicly recognizing and thanking contributors for their hard work and contributions to documentation.

The top monthly contributors and new contributors are thanked on Twitter and in Slack (DevDocs and MerchDocs) each month. The top quarterly contributor will also be recognized through these channels each quarter.

Stay tuned for updates and improvements to the contributor programs for both DevDocs and MerchDocs.

© 2020 Magento. All rights reserved.