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

Update CONTRIBUTING.md (#1105)

Browse source 
* Update CONTRIBUTING.md

* Update CONTRIBUTING.md
This commit is contained in:
Fred K. Schott 2021-08-14 11:14:15 -07:00 committed by GitHub
parent 2347717dea
commit b107d9541a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 64 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

107
CONTRIBUTING.md
View file

@ -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.