|
1 | 1 | # Contributing to simple stack |
2 | 2 |
|
3 | | -Hey contributor 👋 Welcome to simple stack! We're a young project open to contributions of any kind, from fixes to features to documentation and tooling. |
| 3 | +We are only open to contributions to the `www/` documentation site. The remaining packages are here for legacy purposes. |
4 | 4 |
|
5 | | -## Repository overview |
| 5 | +## Prerequisites |
6 | 6 |
|
7 | | -Simple stack is a **monorepo** containing a suite of packages built for Astro. These are the most important directories: |
| 7 | +- [Node 18.14+](https://nodejs.org/en/download) |
| 8 | +- [pnpm](https://pnpm.io/) |
8 | 9 |
|
9 | | -```bash |
10 | | -# packages including `simple-stack-form`, `simple-stack-partial`, etc |
11 | | -packages/* |
12 | | -# Astro projects that use and test these packages |
13 | | -examples/* |
14 | | -``` |
15 | | - |
16 | | -All source code is written in TypeScript, and components may use a variety of frameworks (Astro, React, Vue, Svelte, etc). |
17 | | - |
18 | | -## What to ask before making a PR |
19 | | - |
20 | | -Before submitting a pull request, we suggest asking: |
21 | | - |
22 | | -1. **Have I checked the community discord and existing issue logs first?** We use GitHub issues and [discord discussions](https://wtw.dev/chat) to collaborate on changes. By opening an issue or starting a Discord thread, you can get early feedback on your problem before diving into a solution. |
23 | | - |
24 | | -2. **Have I reviewed the existing documentation?** You may find an answer to your request in the package README. In fact, you might find room to improve our docs for future users with a similar problem. |
25 | | - |
26 | | -If the answer is **yes** to both and you have a PR to contribute, get to it! |
27 | | - |
28 | | -## Prerequisites |
29 | | - |
30 | | -New contributors need the following tools: |
31 | | - |
32 | | -- [Node 18.14+](https://nodejs.org/en/download) for building packages and example sites. |
33 | | -- [pnpm](https://pnpm.io/) to install dependencies. We prefer pnpm since it runs quickly and offers a [robust workspace feature](https://pnpm.io/workspaces) to manage monorepo dependencies. |
34 | | - |
35 | | -## Initial setup |
36 | | - |
37 | | -To get started, clone this repository and install dependencies from the project root: |
| 10 | +## Setup |
38 | 11 |
|
39 | 12 | ```bash |
40 | 13 | git clone https://github.com/bholmesdev/simple-stack.git |
41 | | -cd simple-stack |
| 14 | +cd simple-stack/www |
42 | 15 | pnpm install |
43 | 16 | ``` |
44 | 17 |
|
45 | | -### Linting and formatting |
46 | | - |
47 | | -This project uses [Biome](https://biomejs.dev/) to lint and format code across packages. If you use VS Code, this repository includes a `.vscode/` directory to preconfigure your default linter. [Visit the editor integration docs](https://biomejs.dev/guides/integrate-in-editor/) to enable linting in your editor of choice. |
48 | | - |
49 | | -To run the linter manually, you can use the following commands at the project root: |
50 | | - |
51 | | -```bash |
52 | | -# lint and format all files in packages/* |
53 | | -pnpm check |
54 | | -# apply lint and format fixes to all files in packages/* |
55 | | -pnpm check:apply |
56 | | -# run `lint` or `format` steps individually |
57 | | -pnpm lint |
58 | | -pnpm lint:apply |
59 | | -pnpm format |
60 | | -pnpm format:apply |
61 | | -``` |
62 | | - |
63 | 18 | ## Development |
64 | 19 |
|
65 | | -You may want live compilation for your TypeScript code while working. We use [turborepo](https://turbo.build/) to build packages for development and production. For live reloading, run the following at the project root: |
66 | | - |
67 | 20 | ```bash |
68 | 21 | pnpm dev |
69 | 22 | ``` |
70 | 23 |
|
71 | | -This will build all `packages/*` entries and listen for changes. |
72 | | - |
73 | | -To test your code, you can run any one of our Astro projects under `examples/*`. First open a second terminal, navigate to that example, and run the same `pnpm dev` command. You may need to kill and restart this server to see your package edits take effect. |
| 24 | +The docs site is built with [Astro](https://astro.build/) + [Starlight](https://starlight.astro.build/). |
74 | 25 |
|
75 | | -You can also run packages _and_ examples simultaneously: |
| 26 | +## Linting |
76 | 27 |
|
77 | 28 | ```bash |
78 | | -pnpm dev:all |
| 29 | +pnpm check # check for issues |
| 30 | +pnpm check:fix # auto-fix issues |
79 | 31 | ``` |
80 | | - |
81 | | -However, we've found console logs are harder to read using this approach. Use whichever you prefer! |
82 | | - |
83 | | -## Making a Pull Request |
84 | | - |
85 | | -When requesting a change to a simple stack package, be sure to add a [changeset](https://github.com/changesets/changesets?tab=readme-ov-file#how-do-we-do-that). This is used to specify the version bump for the package, and to update the package CHANGELOG with a description of the change. Note that changes to examples (`examples/*`) do not need changesets. |
86 | | - |
87 | | -To create a new changeset, run the following command: |
88 | | - |
89 | | -```bash |
90 | | -pnpm exec changeset |
91 | | -``` |
92 | | - |
93 | | -Then, provide a brief description of the change. Be sure to focus on the _user-facing change_ (the what), rather than describing _technical implementation_ (the how). |
94 | | - |
95 | | -❌ Apply response headers using the `{ headers }` object in the middleware function. |
96 | | -✅ Fix the missing `text/html` header for Astro routes. |
0 commit comments