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 for creating a PR:

   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. Add any applicable labels to your PR, including Editorial, New topic, Major update, or Technical, depending on the type of revision you are submitting.

7. If your PR fulfills the criteria for adding a New topic, Major update, or Technical label, add a whatsnew to your PR. At the bottom of the PR, add whatsnew immediately followed by a sentence explaining your change and a link to the affected topic. Often, the information you add to the whatsnew is the same description you add in the PR, with the addition of a docs topic link--You can simply copy your PR description and add a link and more context to complete your whatsnew addition!

   Example:

   whatsnew
   Added the [Options section](https://devdocs.magento.com/guides/v2.3/javascript-dev-guide/widgets/widget_confirm.html#confirm_options) to the [Confirm widget](https://devdocs.magento.com/guides/v2.3/javascript-dev-guide/widgets/widget_confirm.html) topic.
   

   This is added to our What's New page to keep everyone up-to-date about documentation changes.

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

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 CLA comment that populates 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. You can 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 or maintainers may request changes of contributor PRs. The PR moves to the Needs writer approval column.

4. Review the change requests and commit updates to the PR. Reply to any comments and questions the Magento Documentation team or maintainers have.

   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 that checks files and links. You will see a "running tests" comment in the PR from the reviewers.

6. If it passes tests, 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.