files/en-us/mdn/community/pull_requests/index.md
This document describes how contributors make changes to MDN Web Docs and how the changes are reviewed and land on the site. Content changes to MDN Web Docs include:
mdn/content repository.Regardless of how content changes are done, they are submitted as pull requests on GitHub. The content changes go through the following stages before they are published on MDN Web Docs:
mdn/content goes live within a day of merging via a site rebuild once every 24 hours.We want MDN Web Docs to be a welcoming, friendly community that we can all be proud of. All participants must follow our Community Participation Guidelines which are derived from Mozilla's Community Participation Guidelines. Be polite and constructive when opening pull requests, writing review comments, interacting with the pull request author or other community members. If you or someone else has experienced behavior that is potentially illegal or makes you feel unsafe, unwelcome, or uncomfortable, we encourage you to report it.
Before you start work on MDN, please go through the recommendations and guidelines listed below.
Pull requests must resolve or partially fix an existing issue. The reason why we have this restriction is to avoid that you start on any kind of task that someone else might already be working on. Search through issues and pull requests in the MDN repository you want to contribute to and confirm that the work you want to start is not already being worked on. When looking to contribute to the MDN project, you will find yourself in one of the following situations:
If you are looking to contribute to the project, you can find tasks under 'Issues' in any of the MDN GitHub repositories (for example, mdn/content issues) and our public GitHub project boards.
Make sure the issue isn't assigned to someone and no one has already opened a pull request for the task.
Issues labelled with good first issue are a good place to start.
If you have found a problem on MDN, you should open an issue first. Issues need a response from maintainers before you start working so that you know a problem addressed by a pull request is valid and that your pull request will be accepted. More information on issues can be found on our Community pages for GitHub issues.
If you want to suggest new content or a new feature, submit a proposal through the 'New content or feature suggestion' GitHub issue template.
If you're not sure where to start, reach out to us on the Discord server and ask for feedback.
When you're ready to open a pull request, follow these guidelines:
.github/workflows).
If one or more of these tests fail, it is your responsibility to try to resolve them.
If you don't know how to resolve the underlying issues, ask for help.mdn/main branch into your branch.
For more information, see the GitHub documentation on keeping your branch up to date.Reviewer(s) are automatically assigned when you open a pull request based on a CODEOWNERS file, but if there is a specific person you want to request review from, you can request a review manually.
We also use auto-labeling on pull requests to help us triage them.
Maintainers can further triage pull requests and add any additional labels, such as needs-info or on-hold, if needed based on context.
If you want to review a pull request but are not listed as a reviewer, you may add yourself as one. It's polite to check with existing reviewers first by commenting on the pull request that you intend to start a review.
The MDN Web Docs team uses reviewers and assignees to track the status of pull requests.
A pull request reviewer or assignee is responsible for merging the changes.
Before you start with a review, check the pull request description to make sure no one specific should review it. Ensure that all continuous integration (CI) tasks have been completed successfully and that there are no merge conflicts.
If any tasks fail or there are merge conflicts, communicate this to the author; it is their responsibility to address these. You may set the author as an assignee to indicate that a pull request needs their attention before a review can start. Do leave the door open to the author to ask for help, especially new contributors to the project.
When it comes to the changes in a pull request, content and prose must adhere to the MDN Writing style guide and example code must follow the code style guide.
When you are reviewing a pull request, you should:
review-help-needed label if you need technical assistance with the review.@core-yari-content team and ask if someone else can step in.main branch stable to avoid disruption for contributors, maintainers, and for automated processes.
An unstable main branch blocks all other pull requests and makes it difficult for others to review and merge contributions.
In addition, contributors who watch repositories receive high volumes of notifications and unnecessary noise caused by failing tests can be frustrating.
If you are not sure how to fix the failing tests, ask for help or assign the pull request to someone else.If a pull request looks good apart from small typos or other minor issues, you may want to fix the problem directly. You can do this provided the pull request has been set up to allow changes. It's recommended to use comments with suggestions for fixing minor issues, as they can be batched and committed in one go.
When submitting your review you have three options, approve, comment, or request changes. The following sections explain when to use each option.
Use the request changes option when the feedback you provided needs to be addressed by the author and re-reviewed by the reviewer before the pull request can be approved and merged.
Use the comment option when your feedback is not critical and will not require a re-review. In short, you trust the author and other reviewers to use good judgment.
Use the approve option when everything looks good and is ready to merge from your perspective. After submitting your review, you can safely merge the pull request if there are no other reviewers or any outstanding review comments to address.
If you don't understand a content change or feel that it is too large and complex for you to deal with, don't panic! A good place to start is by asking for information from the pull request author to help.
It is rare that you'll be required to review a large, complex content change with no warning. If this does happen, however, the pull request description should link to an issue that explains the background information.
If you are still not sure or if you think the content is suspicious, reach out to the MDN Web Docs team and ask for help.
This section provides details for expected turnaround times while responding to review comments if you're a pull request author and while reviewing pull requests if you're a reviewer.
Some pull requests on the MDN content repo relate to specific work by browser vendors or organizations with defined authors and reviewers. The author will include the username of the reviewer in a line at the bottom of the pull request description in these cases, for example:
reviewer: @jpmedley
If you receive a review request and you have been overridden with another reviewer in the manner described above, do not review the changes.
Once the reviewer mentioned in the description has approved the changes, they will ask for an approval required by the CODEOWNERS.
Reviewers are encouraged to read the following articles for help with common tasks: