Skip to content
Astro Docs Docs (AD²)

PR reviews and merging

After you have made a pull request, here’s what happens:

Automated Comment

If you are a first-time contributor, then you will receive a message within a few minutes letting welcoming you and letting you know what to expect.

Checks will run

Some automated checks will need to run to verify your code (check for broken links, or formatting issues that prevent the site from building), and for first-time contributors, a maintainer will need to manually start those checks. This will happen when a maintainer is triaging and labelling your PR, but will not happen automatically. If you have already had a PR merged into docs before, then these checks will run automatically and will start immediately. This will take several minutes.

  • If a GitHub check fails, then usually it is because you have an improperly formatted link. Here’s a quick checklist to cover the most common link errors:

    • Does your link both begin and end with a / (or a /#heading)?
    • Does your link use the language prefix that matches the current page? (e.g. If you are translating /de/getting-started.mdx then any link to another page should also start with /de/)
    • Does your link use the translated heading if you are linking to a translated page? (e.g. Because /de/guides/endpoints.mdx is translated into German, you must link to the translated headings, such as /de/guides/endpoints/#http-methoden instead of #http-methods from the English page.)

  • If a Netlify check fails, then it is usually a syntax error that is preventing the site from being built. (Or, it’s a fluke! 😅) Here are some things you can check:

    • Does every component you are documenting (e.g. <ViewTransitions />) have code backticks around the component? Components must be written as inline code or else Astro will treat it as an actual component.
    • Do all custom components, including code samples, have proper syntax, both opening and closing?
    • Have you imported any components at the top of the file that you are using in the content? (e.g. <Since /> or <PackageManagerTab>)

If you are able to identify and make the fix for a failing check yourself, please do! If you are unsure what is causing a check to fail, then you can wait for a maintainer’s help to fix the problem.

Triage

A maintainer will “triage” your pull request. This process involves adding an appropriate label (e.g. “typo/grammar fix” or “i18n”). The maintainer may not leave you any comment at this time, and may just be in “labelling mode”. No comment does not necessarily mean anything is wrong with your PR. It probably means that a maintainer does not have time to review the contents of your contribution, and is only identifying the kind of contribution right now.

Review

A maintainer will “review” your pull request. At this time, a maintainer will attempt to review your contribution, including the content, the formatting etc. A maintainer may need to ask you questions first before performing a thorough review. For example, the maintainer may be confused about something significant, or may not understand why you have made this contribution, or made it in the way that you did. Here is a list of things that you can check yourself when submitting a PR:

  • Have I made sure that this contribution is something that is expected or welcome? Unexpected PRs, or PRs that do not address a stated need may need more discussion before they can be reviewed. If you are unsure whether a contribution will be welcome or accepted, then it is probably a good idea to file an issue first so that your proposal can be discussed.

    Note: small, obvious corrections like typos, outdated versions of code samples and grammar errors are always expected and welcome! If you notice something incorrect in the docs, and you are positive you know the correct version, then you do not have to ask before making a pull request! 🙌

  • Have I followed the PR template, including any extra information like a link to a related issue or PR to provide extra context and information about this proposed change?

  • Have I selected the “maintainers may edit this PR” option so that a Maintainer can make small changes themselves to your contribution in order to accept it more quickly?

Suggested Changes

When a maintainer leaves a review, there will often be “suggested changes”. These are proposals from the maintainer that show the code that the maintainer would accept in place of something you have submitted. These suggestions can be anything including edits to text content, or adjusting formatting/style to fit the rest of the docs. Because each suggestion shows up as an individual comment, it can sometimes look like a lot, especially for a large contribution! It is usually not as bad as it looks!

If you are happy with the maintainer’s suggestion, you can accept it. This will create a new commit to your branch in the maintainer’s name. Accepting a suggestion automatically “resolves” the comment, and collapses it from view. You can expand it at any time to look at it again.

If you do not accept the maintainer’s suggestion, you can leave a comment underneath it with more explanation or a question. Note that the maintainers will make the final decisions about what to accept into the docs, but they will attempt to understand your point of view.

The “resolve” button can be used by either you or the maintainer when the conversation is considered finished. But, “resolving” does not change your code. You must either click to accept the suggestion, or go back and change your original code.

Approval

When at least one maintainer is satisfied with your contribution, they will “Approve” it and perform the final checks necessary before merging. These are the same checks that ran at when the PR was first opened, but are now checked again with any new changes made and with the latest version of the docs site incorporated. Other PRs have probably merged, changing the docs site itself while your PR was being reviewed!

… and then we welcome you to Team Docs! 🥳 Go to the #docs channel in Discord to see the automated Docsbot report that your PR has merged, and see your first-time contributor personalized announcement!