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,62 +28,34 @@ 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:all +``` + +## Development + +```shell +# starts a file-watching, live-reloading dev script for active development +yarn dev +# (optional) trigger a one-time build yarn build ``` -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: +## Making a Pull Request -```shell -yarn workspace astro run dev -``` - -## Making Pull Requests - -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. - -From the `main` branch do a pull, install and build: - -```shell -git pull origin main -yarn install -yarn build -``` - -Then bump the versions: - -```shell -yarn changeset version -``` - -This should change package.json bumping version numbers and update changelogs. Inspect these to make sure they are what you expect. - -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. - -```shell -cd packages/astro -npm publish -``` - ## Running benchmarks We have benchmarks to keep performance under control. You can run these by running (from the project root): @@ -103,7 +75,56 @@ node test/benchmark/dev.bench.js --save Which will update the build and dev benchmarks. -## Translations + +# Releasing Astro + +_Note: Only priviledged contributors (L3+) can release new versions of Astro._ + +The repo is set up with automatic releases, using the changeset GitHub action & bot. + +To release a new version of Astro, find the `Version Packages` PR, read it over, and merge it. + +## Releasing PR preview snapshots + +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 release a snapshot, run the following locally: + +```shell +# 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 +``` + +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 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.