Pull Request Process

Learn everything you need to know about submitting and reviewing pull requests (PRs) to the DevDocs repository.

Interested in contributing to DevDocs? See our Contributing Guidelines to get started.

Submitting PRs

Submit your PRs directly from your fork. We receive your PR directly to the DevDocs repo.

1. Open your forked repository in GitHub.

2. Click the Pull requests tab, and then click New pull request.

   

3. Select the master branch for the base.

4. Click Create pull request.

5. Enter a PR name and fill out the PR form. Here are some tips!

   Important: We will close your pull request if you do not complete the template.

   • If working an issue, include any related GitHub Issue(s) links.
   • If updating code examples and docs, include links to the Magento 2 source code.
   • Include URLs to existing DevDocs pages you are updating.

6. In the PR description, add a whatsnew describing the topic you added or updated with a link. At the end of the PR, add whatsnew immediately followed by a sentence with the link. This is added to our What's New page.

   For example:

   whatsnew
   Added "Code Sample" section to the [Confirm Widget](https://devdocs.magento.com/guides/v2.3/javascript-dev-guide/widgets/widget_confirm.html) topic.
   

7. Click Create pull request again to submit the PR. That’s it!

For first time contributors only: After the PR is created, you must:

• Fill out and digitally sign the CLA license. This is required for merging PRs to Magento. See the comment in the PR.
• Accept the invite to the Magento organization. After accepting the invitation, we can assign issues to you and you can self-assign issues! See the comment in the PR.

After submitting your PR, the Magento Documentation team adds your PR to the Processing PRs project. Follow your PR as we review, approve, and merge your submission.

Reviewing PRs

Your PR undergoes reviews and testing by Maintainers and the Magento Documentation team before merging.

What happens to your PR:

1. When you submit your PR, we add it to the Backlog of the Processing PRs project.

2. Maintainers and the Magento Documentation team pull PRs from the Backlog column to review.

3. Reviewers may request changes. The PR moves to the Needs writer approval column.

4. Review the change requests and commit updates to the PR. Reply as needed to any comments and questions.

   Important: We will close your PR if you do not respond in two weeks.

5. When a reviewer approves, it moves to the Needs testing column. The Magento Documentation team runs a test build, checking files and links. You will see a message "running tests" from the reviewers.

6. If it passes, the Magento Documentation team merges the PR! Automation publishes the repo hourly.

The Magento Documentation team and Maintainers will add labels for the release line, type of contribution, etc. See DevDocs awards and points for details.

Tips for PRs

• Familiarize yourself with the organization and conventions of our existing documentation before creating a pull request. Changes that are consistent with our style and conventions have a higher acceptance rate.
• If you need to update the site navigation, ask for help in Slack (#devdocs).
• Review your work for basic typos, formatting errors, or ambiguous sentences before opening a pull request.
• Revise pull requests according to review feedback. We will close pull requests that require an inordinate amount of time to review and process (especially for minor changes) if you fail to make revisions according to review feedback.
• Do not directly contact DevDocs team members or maintainers on Slack to review your pull request unless it has been open for more than five days. We have a process and queue for pull requests that everyone must follow.

Small Changes

The Magento Documentation team and Maintainers determine if a PR qualifies as a "small change". Typically, small changes are editorial and/or technical in nature and do not require a significant amount of verification or intervention (such as editing tables or significant new content).

We merge all PRs with the small changes label into a single PR that is reviewed, tested, and merged to the master branch. This process reduces testing time and speeds up merges to DevDocs. You still receive contribution points for your PR work.