Code contributions

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

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.

Priority and severity descriptions

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.

Severity

• Community Maintainers are allowed to set Severity labels during the initial issue triage according to the Issue Processing Workflow.
• The Adobe 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.

Pull request risk assessment

The 'Risk:' label highlights the risk that the suggested changes may bring to the platform. It helps maintainers decide:

• to which version the pull requests should be delivered
• which reviewers should see it
• whether a request should be approved or not

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 DevDocs repo. 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 Feature Requests and Improvements forum. For details about how requests are managed, see Improvements to GitHub Management.

Accepted pull requests and ported code

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
2.2
2.3
2.4

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:
   • Unit/integration test coverage (we will be releasing more information about writing test coverage in the near future).
   • Follow the DevDocs contribution work flow and guidelines to submit proposed documentation updates to the DevDocs Github repository.
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:

• Select an issue to work on and self-assign
• Fork a repository
• Create a branch
• Fix/implement the functionality
• Cover the changes with tests
• Open a pull request
• Launch tests and ensure they are green (see more details on pull request tests)

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:

Copy
@magento I am working on this
Copied to your clipboard
@magento I am working on this

This command has several variations:

Copy
@magento I am working on this
@magento I am working on it
@magento I'm working on this
@magento I'm working on it
Copied to your clipboard
@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 Contributor Assistant automatically deploys a test instance based on a contributor's pull request, or, it provides a vanilla Magento Open Source instance on the magento/magento2 repository. This is used to test pull requests or reported issues.

• Deploy vanilla Magento Open Source instance
• Deploy instance based on PR changes
• Customize deployed instances

Deploy vanilla Magento Open Source instance

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

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

Copy
@magento give me {$version} instance
Copied to your clipboard
@magento give me {$version} instance

Replace {$version} with the version tag or branch. The following values are supported: the version tag for the latest release and 2.4-develop for the development branch.

Copy
@magento give me 2.4.3 instance
Copied to your clipboard
@magento give me 2.4.3 instance

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 Open Source instance using code based on the PR.

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

Copy
@magento give me test instance
Copied to your clipboard
@magento give me test instance

Actions:

• It deploys a new 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:

• Community Maintainers
• Adobe EngCom Team
• Contributor

Customize deployed instances

In some cases a custom environment is required to test an issue or a pull request. You can create a custom environment by appending custom configuration settings to the PR comment to Deploy a vanilla Magento Open Source instance or Deploy an instance based on PR changes.

Specify the edition

Append the following text to your PR comment to specify the edition to use when you Deploy a vanilla Magento Open Source instance or Deploy an instance based on PR changes.

Copy
with edition {$edition}
Copied to your clipboard
with edition {$edition}

Replace {$edition} with either of the following values:

• ee deploys the Adobe Commerce edition
• b2b deploys Adobe Commerce with B2B modules.

For example, append the following text to the PR comment to deploy a Adobe Commerce instance with B2B modules:

Copy
with edition b2b
Copied to your clipboard
with edition b2b

Add extensions

Append the following text to your PR comment to specify extensions to add to an instance when you Deploy a vanilla Magento Open Source instance or Deploy an instance based on PR changes.

Copy
with extensions {$extensionRepo}
Copied to your clipboard
with extensions {$extensionRepo}

Replace {$extensionRepo} with one or more extension repositories to include when compiling your instance. If you specify multiple repositories, use a comma after each repository. You can specify a specific branch in a repository using the pattern: org/repo-name:branch-name. For example:

Copy
with extensions magento/security-package:1.0-develop, magento/security-package-ee
Copied to your clipboard
with extensions magento/security-package:1.0-develop, magento/security-package-ee

Remove extensions

Append the following text to your PR comment to specify extensions that you want to remove from the instance when you Deploy a vanilla Magento Open Source instance or Deploy an instance based on PR changes.

Copy
without extensions {$extensionRepo}
Copied to your clipboard
without extensions {$extensionRepo}

Replace {$extensionRepo} with one or more extension repositories to remove before compiling your instance. If you specify multiple repositories, use a comma after each repository. For example:

Copy
without extensions magento/adobe-stock-integration
Copied to your clipboard
without extensions magento/adobe-stock-integration

Import source code to specific repository

The import command provides the ability to copy a contributor's code or pull request into an internal fork. The internal team can then proceed with additional fixes or delivery.

Command: To import code or a pull request, a member of the Adobe team controlling the pull request enters the following command:

Copy
@magento import {code|pr} to {organizationName}/{repositoryName}
Copied to your clipboard
@magento import {code|pr} to {organizationName}/{repositoryName}

Usage Examples:

• To import the code only use

Copy
@magento import code to magento-team/magento2
@magento import code to https://github.com/magento-team/magento2
Copied to your clipboard
@magento import code to magento-team/magento2
@magento import code to https://github.com/magento-team/magento2

• To import the pull request use

Copy
@magento import pr to magento-team/magento2
@magento import pull request to magento-team/magento2
@magento import pr to https://github.com/magento-team/magento2
@magento import pull request to https://github.com/magento-team/magento2
Copied to your clipboard
@magento import pr to magento-team/magento2
@magento import pull request to magento-team/magento2
@magento import pr to https://github.com/magento-team/magento2
@magento import pull request to https://github.com/magento-team/magento2

Actions:

• Code: A branch with a copy of the contributor's source code is created within the target repository.
• PR: A copy of the pull request is created within the target repository.

Permissions:

• Adobe team

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:

• Check the Developer Documentation and User Guide 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.

• Ensure that information you are reporting is a technical issue. Refer to the Community Forums or Magento Stack Exchange for technical questions, feature requests, etc.

• Verify that the issue you are reporting does not relate to Adobe Commerce. GitHub is intended for Magento Open Source users to report on issues related to Open Source only. You can report Commerce-related issues one of two ways:

  • Use the Support portal associated with your account
  • If you are a Partner reporting on behalf of a merchant, use the Partner portal

• Check if the issue exists on the 2.4-develop branch with a clean installation. We only accept pull requests for the 2.4-develop branch. If the issue is not reproducible on the 2.4-develop branch, it will be closed.

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. More information on gates is available in Magento Issue Gates.

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:

• System configuration settings you have changed
• Detailed information on entities created (Products, Customers, etc)
• Magento Open Source version
• Anything else that would help a developer reproduce the bug

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.

Once the issue is created, it must pass through a series of Magento Issue Gates.

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

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

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 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 the 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

Last updated 10/29/2024

Was this helpful?

Yes

No