Skip to content

The pull request process

You will describe the nature of your contribution as a change to the Astro codebase in a changeset directly in your code contribution PR.

If a change to user-facing docs is required, you will usually make a second, additional PR to the docs repo.

Changesets

You will be responsible for writing a changeset for your Astro PR. This is a Markdown file that states which repository has changed, the kind of change according to Astro’s semantic versioning, and a message describing the change that will be publicly displayed on the repo’s CHANGELOG:

my-super-cool-changeset.md
---
'astro': patch
---
Updates `getCollection()` to always return a cloned array

Format

Begin your changeset message with a present tense verb that completes a sentence in the style of: “This PR …” or “This contribution …”

  • Adds
  • Removes
  • Fixes
  • Updates
  • Refactors
  • Improves
  • Deprecates

Focus on what’s changed

The changeset must focus on what has changed, and must include any breaking changes, including changes to default behavior. Most users will have several default settings configured (often by not setting any value themselves), so changes to defaults can have a significant impact on someone’s project!

Not all changes are user-facing, requiring an update to their own project code. Verbs like “fixes” and “refactors” are helpful to let readers know this is an internal or implementation change that they do not need to worry about. At the same time, these messages are helpful to someone who is interested in keeping up with small changes to the codebase.

For new features, verbs like “adds” alert readers that there is something new (e.g. Adds a new flamethrow view transitions animation). It is important both mention the names of any new items (options, functions) that have been added, and to describe what people are now able to do because of these additions that they could not before. The changeset is an opportunity to call people’s attention to new things they might wish to try in their Astro project.

Docs

Your contribution to Astro may require an additional PR directly to the docs repo, depending on the nature of your code changes.

If you have never made a pull request (PR) to Astro docs, you can learn more about contributing with a fork of the docs repo or making smaller edits to a single page as well as our PR review and merging process in our First-Time Contributors section.

Where to find docs source content

The source content for Astro’s documentation lives within two different repositories:

  1. The main astro repository contains:

  2. All other content, including all non-English lanaguage content, is found within the Astro docs repo itself: https://github.com/withastro/docs

Be sure to fill out the PR template for the docs repo, which will allow you to link an implementation PR to a corresponding docs PR.

Requesting a review from Docs

Team Docs reviews all text changes to the Astro documentation. Some exceptions include obvious typos and link fixes where no actual content changed. However, even a tiny change in wording of our documentation is reason to wait for a review from one of our Docs Maintainers.

Use the /ptal command in Discord in the #docs-ptal channel if you have access (Astro maintainers) or the regular #docs channel otherwise.

Alternatively, for PRs not in the docs repo, you can mention the role @withastro/maintainers-docs in your PR which will notify all Astro maintainers with the docs role.

Waiting for a review from Docs

Even a minor change in phrasing can change the nuance of a sentence. Docs would typically prefer to see these changes before merging, however small, unless they are truly fixes/corrections.

Additionally, the word or phrase you are changing may be used in other parts of the documentation as “standard wording” and a change here might mean updating other parts of the page or site. For example, you may be updating the way you describe the usage of one integration or adapter, but we might have a corresponding section or example for each one that should therefore also change.

The docs maintainers have a “big picture” awareness of the larger effects a smaller change may have throughout the rest of the documentation, and work to ensure consistency across the entire site.

Getting a Docs approval

It is very common for several people to review docs PRs, and not all approvals mean that your PR can be merged.

Team Docs encourages our community members to review PRs to catch small problems before docs maintainers edit larger contributions, or even to practice their own reviewing skills!

All new feature documentation must be approved by the Docs Lead personally before the PR is considered ready to merge.

Merging your own PRs as a maintainer

Astro maintainers are welcome to merge their own PRs in either repo (astro or docs) after appropriate docs approval for small updates and fixes that can be published to docs immediately (i.e. they do not document an upcoming, unreleased feature).

There is a nightly GitHub action to create a PR to the docs repo with any documentation changes from the core repo. These docs changes will therefore typically be published on the docs site the next day after merging. This action can also be run manually to expedite the process, and is regularly done so for major and minor releases.

Docs for upcoming features

Unlike PRs to the astro repo, PRs to the docs repo are published live immediately upon merging. Therefore, the docs repo labels upcoming feature docs with merge on release and waits for a feature to released before updating the live docs site.

Minor releases happen every other Tuesdays for the astro core package itself and the Docs Lead prepares and merges these docs on a regular schedule. Even as a maintainer, you will not merge these PRs yourself.

Other packages, such as integrations, only release when necessary. These merge on release docs are released alongside the package as appropriate and may be merged by any maintainer when approved.