michael/astro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: improve CONTRIBUTING.md (#6867)

Browse source 
Co-authored-by: Elian ☕️ <hello@elian.codes>
This commit is contained in:
Han Yeong-woo 2023-04-18 23:44:38 +09:00 committed by GitHub
parent 0c82e08cec
commit dec072f57f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 13 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
CONTRIBUTING.md
View file

@ -7,17 +7,17 @@ We welcome contributions of any size and skill level. As an open source project,
## Quick Guide ## Quick Guide
### Prerequisite ### Prerequisites
```shell ```shell
node: "^14.18.0 || >=16.12.0" node: "^>=16.12.0"
pnpm: "^7.9.5" pnpm: "^8.2.0"
# otherwise, your build will fail # otherwise, your build will fail
``` ```
### Setting up your local repo ### Setting up your local repo
Astro uses pnpm workspaces, so you should **always run `pnpm install` from the top-level project directory.** running `pnpm install` in the top-level project root will install dependencies for `astro`, and every package in the repo. Astro uses pnpm workspaces, so you should **always run `pnpm install` from the top-level project directory**. Running `pnpm install` in the top-level project root will install dependencies for `astro`, and every package in the repo.
```shell ```shell
git clone && cd ... git clone && cd ...
@ -35,7 +35,7 @@ To automatically handle merge conflicts in `pnpm-lock.yaml`, you should run the
```shell ```shell
pnpm add -g @pnpm/merge-driver pnpm add -g @pnpm/merge-driver
pnpx npm-merge-driver install --driver-name pnpm-merge-driver --driver "pnpm-merge-driver %A %O %B %P" --files pnpm-lock.yaml pnpm dlx npm-merge-driver install --driver-name pnpm-merge-driver --driver "pnpm-merge-driver %A %O %B %P" --files pnpm-lock.yaml
``` ```
### Using GitHub Codespaces for development ### Using GitHub Codespaces for development
@ -44,7 +44,7 @@ To get started, create a codespace for this repository by clicking this 👇
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/withastro/astro) [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/withastro/astro)
Your new codespace will open in a web-based version of Visual Studio Code. All development dependcies will be preinstalled and the tests will run automatically ensuring you've got a green base from which to start working. Your new codespace will open in a web-based version of Visual Studio Code. All development dependencies will be preinstalled, and the tests will run automatically ensuring you've got a green base from which to start working.
**Note**: Dev containers is now an open spec which is supported by [GitHub Codespaces](https://github.com/codespaces) and [other supporting tools](https://containers.dev/supporting). **Note**: Dev containers is now an open spec which is supported by [GitHub Codespaces](https://github.com/codespaces) and [other supporting tools](https://containers.dev/supporting).
@ -63,7 +63,7 @@ During the development process, you may want to test your changes to ensure they
1. Run any of the examples in the `/examples` folder. They are linked to use the local Astro source code, so you can see the effects of your changes. 1. Run any of the examples in the `/examples` folder. They are linked to use the local Astro source code, so you can see the effects of your changes.
``` ```shell
pnpm --filter @example/minimal run dev pnpm --filter @example/minimal run dev
``` ```
@ -77,7 +77,7 @@ Overall, it's up to personal preference which method to use. For smaller changes
You can debug vite by prefixing any command with `DEBUG` like so: You can debug vite by prefixing any command with `DEBUG` like so:
``` ```shell
DEBUG=vite:* astro dev # debug everything in Vite DEBUG=vite:* astro dev # debug everything in Vite
DEBUG=vite:[name] astro dev # debug specific process, e.g. "vite:deps" or "vite:transform" DEBUG=vite:[name] astro dev # debug specific process, e.g. "vite:deps" or "vite:transform"
``` ```
@ -168,7 +168,7 @@ Server-side rendering (SSR) can be complicated. The Astro package (`packages/ast
- `core/`: Code that executes **in the top-level scope** (in Node). Within, you’ll find code that powers the `astro build` and `astro dev` commands, as well as top-level SSR code. - `core/`: Code that executes **in the top-level scope** (in Node). Within, you’ll find code that powers the `astro build` and `astro dev` commands, as well as top-level SSR code.
- `runtime/`: Code that executes **in different scopes** (i.e. not in a pure Node context). You’ll have to think about code differently here. - `runtime/`: Code that executes **in different scopes** (i.e. not in a pure Node context). You’ll have to think about code differently here.
- `client/`: Code that executes **in the browser.** Astro’s partial hydration code lives here, and only browser-compatible code can be used. - `client/`: Code that executes **in the browser.** Astro’s partial hydration code lives here, and only browser-compatible code can be used.
- `server/`: Code that executes **inside Vite’s SSR.** Though this is a Node environment inside, this will be executed independently from `core/` and may have to be structured differently. - `server/`: Code that executes **inside Vite’s SSR.** Though this is a Node environment inside, this will be executed independently of `core/` and may have to be structured differently.
- `vite-plugin-*/`: Any Vite plugins that Astro needs to run. For the most part, these also execute within Vite similar to `src/runtime/server/`, but it’s also helpful to think about them as independent modules. _Note: at the moment these are internal while they’re in development_ - `vite-plugin-*/`: Any Vite plugins that Astro needs to run. For the most part, these also execute within Vite similar to `src/runtime/server/`, but it’s also helpful to think about them as independent modules. _Note: at the moment these are internal while they’re in development_
### Thinking about SSR ### Thinking about SSR
@ -198,7 +198,7 @@ By default, `create-astro` and [astro.new](https://astro.new) point to this bran
## Releasing Astro ## Releasing Astro
_Note: Only [core maintainers (L3+)](https://github.com/withastro/.github/blob/main/GOVERNANCE.md#level-3-l3---core-maintainer) can release new versions of Astro._ _Note: Only [core maintainers (L3+)](https://github.com/withastro/.github/blob/main/GOVERNANCE.md#level-3-l3---core) can release new versions of Astro._
The repo is set up with automatic releases, using the changeset GitHub action & bot. The repo is set up with automatic releases, using the changeset GitHub action & bot.
@ -230,15 +230,15 @@ git reset --hard
By default, every package with a changeset will be released. If you only want to target a smaller subset of packages for release, you can consider clearing out the `.changesets` directory to replace all existing changesets with a single changeset of only the packages that you want to release. Just be sure not to commit or push this to `main`, since it will destroy existing changesets that you will still want to eventually release. By default, every package with a changeset will be released. If you only want to target a smaller subset of packages for release, you can consider clearing out the `.changesets` directory to replace all existing changesets with a single changeset of only the packages that you want to release. Just be sure not to commit or push this to `main`, since it will destroy existing changesets that you will still want to eventually release.
Full documentation: https://github.com/atlassian/changesets/blob/main/docs/snapshot-releases.md Full documentation: https://github.com/changesets/changesets/blob/main/docs/snapshot-releases.md
### Releasing `astro@next` (aka "prerelease mode") ### Releasing `astro@next` (aka "prerelease mode")
Sometimes, the repo will enter into "prerelease mode". In prerelease mode, our normal release process will publish npm versions under the `next` dist-tag, instead of the default `latest` tag. We do this from time-to-time to test large features before sharing them with the larger Astro audience. Sometimes, the repo will enter into "prerelease mode". In prerelease mode, our normal release process will publish npm versions under the `next` dist-tag, instead of the default `latest` tag. We do this from time-to-time to test large features before sharing them with the larger Astro audience.
While in prerelease mode, follow the normal release process to release `astro@next` instead of `astro@latest`. To release `astro@latest` instead, see [Releasing `astro@latest` while in prerelease mode](#user-content-releasing-astrolatest-while-in-prerelease-mode). While in prerelease mode, follow the normal release process to release `astro@next` instead of `astro@latest`. To release `astro@latest` instead, see [Releasing `astro@latest` while in prerelease mode](#releasing-astrolatest-while-in-prerelease-mode).
Full documentation: https://github.com/atlassian/changesets/blob/main/docs/prereleases.md Full documentation: https://github.com/changesets/changesets/blob/main/docs/prereleases.md
### Entering prerelease mode ### Entering prerelease mode