Update CONTRIBUTING.md (#1105)

* Update CONTRIBUTING.md

* Update CONTRIBUTING.md

1 files changed, 58 insertions, 37 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b656287ff..868cd27c1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,7 +19,7 @@ The Astro community is my personal attempt to share this experience with others
 - **preventing imposter syndrome:** Sure, I was still just a kid, but having an actual human connection to developers who I looked up to at the time helped dispell the idea that "oh, **I** could never be like that."
 - **Making friends in the larger community:** The creator of request, [@mikeal](https://twitter.com/mikeal), is still a friend to this day.
 
-If any of this sounds interesting, I hope you consider getting involved with Astro. Come say hi in the **#new-contributors** channel on Discord, anytime. We're always around and value contributions of any shape/size.
+If any of this sounds interesting, I hope you consider getting involved with Astro. Come say hi in the [**#new-contributors**](https://astro.build/chat) channel on Discord, anytime. We're always around and value contributions of any shape/size.
 
 # Contributor Manual
 
@@ -28,82 +28,103 @@ If any of this sounds interesting, I hope you consider getting involved with Ast
 ```shell
 node: "^12.20.0 || ^14.13.1 || >=16.0.0"
 yarn: "^1.22.10"
-# otherwise, build will fail
+# otherwise, your build will fail
 ```
 
-## Setting Up the Monorepo
+## Setting up the monorepo
 
 ```shell
 # git clone && cd ...
 yarn install
-yarn build
+yarn build:all
 ```
 
-Most of the packages have a dev script that will recompile when a file changes. For example when working on the `astro` package you can run:
+## Development
 
 ```shell
-yarn workspace astro run dev
+# starts a file-watching, live-reloading dev script for active development
+yarn dev
+# (optional) trigger a one-time build
+yarn build
 ```
 
-## Making Pull Requests
+## Making a Pull Request
 
-When making a pull request, add a changeset which helps with releases.
+When making a pull request, be sure to add a changeset when something has changed with Astro. Non-packages (`examples/*`, `docs/*`, and `www/*`) do not need changesets.
 
 ```shell
 yarn changeset
 ```
 
-This will prompt you asking what type of change was made.
-
-## Releases
-
-For those contributors that have access to publish to npm, the following is how you do releases.
+## Running benchmarks
 
-From the `main` branch do a pull, install and build:
+We have benchmarks to keep performance under control. You can run these by running (from the project root):
 
 ```shell
-git pull origin main
-yarn install
-yarn build
+yarn workspace astro run benchmark
 ```
 
-Then bump the versions:
+Which will fail if the performance has regressed by **10%** or more.
+
+To update the times cd into the `packages/astro` folder and run the following:
 
 ```shell
-yarn changeset version
+node test/benchmark/build.bench.js --save
+node test/benchmark/dev.bench.js --save
 ```
 
-This should change package.json bumping version numbers and update changelogs. Inspect these to make sure they are what you expect.
+Which will update the build and dev benchmarks.
 
-Commit and push these changes, then run an npm publish for each of the packages that have changed.
 
-> **Important**! Ordering publishes can be important. If `@astrojs/parser` changes you should publish that before `astro`, for example.
+# Releasing Astro
 
-```shell
-cd packages/astro
-npm publish
-```
+_Note: Only priviledged contributors (L3+) can release new versions of Astro._
 
-## Running benchmarks
+The repo is set up with automatic releases, using the changeset GitHub action & bot. 
 
-We have benchmarks to keep performance under control. You can run these by running (from the project root):
+To release a new version of Astro, find the `Version Packages` PR, read it over, and merge it.
 
-```shell
-yarn workspace astro run benchmark
-```
+## Releasing PR preview snapshots
 
-Which will fail if the performance has regressed by **10%** or more.
+Our release tool `changeset` has a feature for releasing "snapshot" releases from a PR or custom branch. These are npm package publishes that live temporarily, so that you can give users a way to test a PR before merging. This can be a great way to get early user feedback while still in the PR review process.
 
-To update the times cd into the `packages/astro` folder and run the following:
+To release a snapshot, run the following locally:
 
 ```shell
-node test/benchmark/build.bench.js --save
-node test/benchmark/dev.bench.js --save
+# Note: XXX should be a keyword to identify this release. Ex: `--snapshot routing` & `--tag next--routing`
+
+# 1:
+yarn changeset version --snapshot XXX
+# 2: (Manual) review the diff, and make sure that you're not releasing more than you need to.
+git checkout -- examples/ docs/ www/
+# 3:
+yarn release --tag next--XXX
 ```
 
-Which will update the build and dev benchmarks.
+Full documentation: https://github.com/atlassian/changesets/blob/main/docs/snapshot-releases.md
+
+
+
+## Releasing in "next"/"pre" mode
+
+Sometimes, the repo enters "next" mode, which means that `main` is no longer releasing to `npm install astro` but is instead releasing to `npm install astro@next`. We do this from time-to-time to test large features before sharing them with the larger Astro audience.
+
+When in "next" mode, the automatic PR release process is for `next`. That means that releasing to `latest` becomes a manual process. To release latest manually while in "next" mode:
+
+1. *In the code snippets below, replace `0.X` with your version (ex: `0.18`, `release/0.18`, etc.).*
+1. Create a new `release/0.X` branch, if none exists. 
+1. Point `release/0.X` to the latest commit for the `v0.X` version.
+1. `git cherry-pick` commits from `main`, as needed.
+1. Make sure that all changesets for the new release are included. You can create some manually (via `yarn changeset`) if needed.
+1. Run `yarn changeset version` to create your new release.
+1. Run `yarn release` to publish your new release.
+1. Run `git push && git push --tags` to push your new release to GitHub.
+1. Run `git push release/0.X:latest` to push your release branch to `latest`. This will trigger an update to the docs site, the www site, etc.
+1. Go to https://github.com/snowpackjs/astro/releases/new and create a new release. Copy the new changelog entry from https://github.com/snowpackjs/astro/blob/latest/packages/astro/CHANGELOG.md.
+1. Post in Discord #announcements channel, if needed!
+
 
-## Translations
+# Translations
 
 Help us translate [docs.astro.build](https://docs.astro.build/) into as many languages as possible! This can be a great way to get involved with open source development without having to code.