0
Fork 0
mirror of https://github.com/withastro/astro.git synced 2024-12-16 21:46:22 -05:00
astro/STYLE_GUIDE.md

69 lines
4.2 KiB
Markdown
Raw Normal View History

2021-11-18 19:04:32 -05:00
# Style Guide
Welcome to the Astro style guide. This document is meant to guide you on the coding & writing styles of all content within the Astro repo, including:
- TypeScript & JavaScript coding style
- Blog post writing style
- Discord/Twitter writing style
2021-11-23 17:47:05 -05:00
For the RFC writing guide, check out the [RFC issue template](https://github.com/withastro/astro/issues/new/choose).
2021-11-18 19:04:32 -05:00
### Linting (Style Rules)
Move from yarn to pnpm (#2455) * chore: `yarn` => `pnpm` * docs: `yarn` => `pnpm` * chore(ci): yarn => pnpm * chore(ci): update pnpm cache path * fix: add missing deps * fix: add missing deps * test: add package.json to all test fixtures * chore: improve hoisting behavior * chore: move turbo into package.json * chore: update npmrc * fix: add missing `debug` dependency * chore: remove prepare script * test: fix new tests * fix: fully resolve renderer paths and `astro/internal` path * chore: update lockfile * chore: remove log * fix: resolve renderers in vite-plugin-jsx * fix: prefer public-hoist-pattern to shamefully-hoist * chore: ignore @babel/core peer warning * chore: update dependencies * test: add autoprefixer as explicit dep * chore: update `.npmrc` file in examples * chore: update dependencies * fix: resolve renderer dependencies in static build * fix: static build renderer resolution * chore: fix smoke tests * chore: hoist autoprefixer * chore: update lockfile * attempt: use full file:// path on Windows * attempt: use astro/internal * attempt: optimize astro/internal * attempt: expose ./internal.js * chore: add missing package.json files * attempt: resolve astro/internal path * chore: tidy package.json * chore: update lockfile * chore: update deps * chore: update deps * chore: yarn -> pnpm * attempt: explicit /@fs urls * attempt: explicit /@fs urls * chore: update all examples for pnpm * chore: fix hoisting for with-vite-plugin-pwa * chore(ci): fix sharp install * chore: update with-vite-plugin-pwa example * fix: pin vite-plugin-pwa to 0.11.11 * fix: add workbox-window to vite-plugin-pwa deps * refactor: use pnpm update --recursive Co-authored-by: JuanM04 <me@juanm04.com> * chore: yarn => pnpm * chore: yarn => pnpm * fix: update smoke test to skip examples which don't work in static build * update lockfile * chore: update .npmrc files * chore: update lockfile * fix: smoke script * chore: update .npmrc file * fix: return to shamefully-hoist (shamefully) * chore: update lockfile * fix(smoke): ignore scripts for smoke tests * fix: update example to disable renderers * chore: bump version * chore(ci): fix smoke tests * attempt: disable --frozen-lockfile for smoke tests * chore: update smoke test * chore: fix rebase issue * chore: update lockfile * fix: smoke tests * fix(ci): run external smoke tests first * fix(ci): run syntax * chore: update lockfile * fix(ci): ensure submodules are up-to-date * fix(ci): ensure submodules are up-to-date * chore: update lockfile * chore: update for webapi * chore: silence node:* warnings * chore: update deps * fix(ci): persist generated webapi assets * fix(ci): webapi build script * chore(ci): remove custom node caching * chore: keep turbo.json * chore: update turbo, ignore create-astro * chore: update deps * fix(ci): test command * chore(ci): update test script Co-authored-by: JuanM04 <me@juanm04.com>
2022-03-08 16:46:11 -05:00
We use tools like ESLint and TypeScript to automatically enforce some parts of our style guide. Run the `pnpm run lint` command to lint the codebase. We also use tools like Prettier to automatically enforce code formatting. Run the `pnpm run format` command to format the entire codebase.
2021-11-18 19:04:32 -05:00
Move from yarn to pnpm (#2455) * chore: `yarn` => `pnpm` * docs: `yarn` => `pnpm` * chore(ci): yarn => pnpm * chore(ci): update pnpm cache path * fix: add missing deps * fix: add missing deps * test: add package.json to all test fixtures * chore: improve hoisting behavior * chore: move turbo into package.json * chore: update npmrc * fix: add missing `debug` dependency * chore: remove prepare script * test: fix new tests * fix: fully resolve renderer paths and `astro/internal` path * chore: update lockfile * chore: remove log * fix: resolve renderers in vite-plugin-jsx * fix: prefer public-hoist-pattern to shamefully-hoist * chore: ignore @babel/core peer warning * chore: update dependencies * test: add autoprefixer as explicit dep * chore: update `.npmrc` file in examples * chore: update dependencies * fix: resolve renderer dependencies in static build * fix: static build renderer resolution * chore: fix smoke tests * chore: hoist autoprefixer * chore: update lockfile * attempt: use full file:// path on Windows * attempt: use astro/internal * attempt: optimize astro/internal * attempt: expose ./internal.js * chore: add missing package.json files * attempt: resolve astro/internal path * chore: tidy package.json * chore: update lockfile * chore: update deps * chore: update deps * chore: yarn -> pnpm * attempt: explicit /@fs urls * attempt: explicit /@fs urls * chore: update all examples for pnpm * chore: fix hoisting for with-vite-plugin-pwa * chore(ci): fix sharp install * chore: update with-vite-plugin-pwa example * fix: pin vite-plugin-pwa to 0.11.11 * fix: add workbox-window to vite-plugin-pwa deps * refactor: use pnpm update --recursive Co-authored-by: JuanM04 <me@juanm04.com> * chore: yarn => pnpm * chore: yarn => pnpm * fix: update smoke test to skip examples which don't work in static build * update lockfile * chore: update .npmrc files * chore: update lockfile * fix: smoke script * chore: update .npmrc file * fix: return to shamefully-hoist (shamefully) * chore: update lockfile * fix(smoke): ignore scripts for smoke tests * fix: update example to disable renderers * chore: bump version * chore(ci): fix smoke tests * attempt: disable --frozen-lockfile for smoke tests * chore: update smoke test * chore: fix rebase issue * chore: update lockfile * fix: smoke tests * fix(ci): run external smoke tests first * fix(ci): run syntax * chore: update lockfile * fix(ci): ensure submodules are up-to-date * fix(ci): ensure submodules are up-to-date * chore: update lockfile * chore: update for webapi * chore: silence node:* warnings * chore: update deps * fix(ci): persist generated webapi assets * fix(ci): webapi build script * chore(ci): remove custom node caching * chore: keep turbo.json * chore: update turbo, ignore create-astro * chore: update deps * fix(ci): test command * chore(ci): update test script Co-authored-by: JuanM04 <me@juanm04.com>
2022-03-08 16:46:11 -05:00
Anything enforced by linting and formatting is considered a **style rule.** It is strictly required that you follow all style rules while working in the codebase. Run the `pnpm run lint` and `pnpm run format` commands to check your code at any time.
2021-11-18 19:04:32 -05:00
These style rules are maintained in configuration files, and therefore not documented in this document. Read any of the following configuration files to learn more about the style rules that we strictly enforced across the codebase:
2021-11-18 19:05:47 -05:00
- [ESLint](https://github.com/withastro/astro/blob/main/eslint.config.js) (Linting)
- [Prettier](https://github.com/withastro/astro/blob/main/prettier.config.js) (Formatting)
2021-11-18 19:04:32 -05:00
Alternatively, don't worry too much about style rules and trust that our tools will catch these issues for you and offer inline suggestions as you work.
### Style Rules vs. Style Guidance
We will try to enforce most of our style guide with linting and formatting tools, but not everything can be reasonably captured in a lint rule.
2021-11-18 19:05:47 -05:00
Anything else in this document -- that is, anything not automatically enforced by linting -- is considered **style guidance.** Do your best to follow all style guidance outlined in this style guide, and expect code reviewers to be looking for these things in your Pull Request. However, no tool exists to catch you when you break guidance.
2021-11-18 19:04:32 -05:00
The reason that we don't treat these as strict rules is simple: we are all human. It would be silly to expect 100% accuracy without automated tooling to enforce it. Authors and reviewers will both miss things every once-in-a-while, and that is okay.
### How to Request a Style Change
Currently, style rule changes must be nominated by a core maintainer (L3) to be considered for the official style guide. Anyone is free to suggest a change, but do not expect any action unless a core maintainer champions your proposal through the process.
_Note: This process is new, we are still figuring it out! This process will be moved into GOVERNANCE.md when finalized._
_If you are a core maintainer who is interested in nominating or championing a style change, reach out in the private #core channel on Discord._
### How to Evaluate a Style Change
Style changes should be evaluated as objectively as possible, with as little personal ego invested as possible.
For example: "This is clean code" is a subjective point and should have limited impact in a style discussion. What is clean code to you may be "dirty" code to me!
In contrast: "Tabs are more accessible than spaces" is an objective point and should be strongly considered in a theoretical style discussion on tabs vs. spaces. (Fred: Believe me, I write this as someone who personally prefers spaces over tabs in my own code!)
Sometimes, not everyone will agree on style changes and 100% consensus is impossible. This is a condition commonly referred to as bike-shedding. If consensus can not be reached, a simple majority vote among core contributors (L3) will suffice.
_Note: This process is new, we are still figuring it out! This process will be moved into GOVERNANCE.md when finalized._
## TypeScript Style Guide
2021-11-18 19:05:47 -05:00
Empty! Right now, everything in our official style guide is captured and enforced as style rules in the automated tooling, as outlined above.
2021-11-18 19:04:32 -05:00
## Writing
### Blog Posts: Brief Announcement
TODO. For now, see an example: https://astro.build/blog/astro-repl/
### Blog Posts: Detailed Announcement
TODO. For now, see an example: https://astro.build/blog/astro-021-preview/
### Tweet: Announcement
TODO. For now, see an example: https://twitter.com/astrodotbuild