Skip to content

Commit d7e8850

Browse files
atilafassinaatilafassina
committed
overhaul CONTRIBUTING and README
1 parent 0a1208e commit d7e8850

File tree

2 files changed

+163
-99
lines changed

2 files changed

+163
-99
lines changed

‎CONTRIBUTING.md‎

Lines changed: 38 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,123 +1,62 @@
11
# Contributing
22

3-
Thank you for your interest in contributing to **SolidStart**! We welcome contributions including bug fixes, feature enhancements, documentation improvements, and more.
3+
Thank you for your interest in contributing to **SolidStart**.
4+
We welcome contributions including bug fixes, feature enhancements, documentation improvements, and more.
45

5-
## Prerequisites
6+
## Creating a Template
67

7-
- **Node.js**: Use the version specified in `.nvmrc`, to manage multiple versions across your system, we recommend a version manager such as [fnm](https://github.com/Schniz/fnm), or another of your preference.
8-
- **pnpm**: Install globally via `npm install -g pnpm`. Or let **Corepack** handle it in the setup step below.
9-
- **Git**: Ensure Git is installed for cloning and managing the repository
8+
We do not maintain official templates and integration in this monorepo.
9+
Instead, please head over to [solidjs/templates](https://github.com/solidjs/templates) to submit your contribution.
1010

11-
## Setup
11+
## Feature Request
1212

13-
1. Clone the repository
13+
> [!IMPORTANT]
14+
> Do not create a PR without first discussion in an issue
1415
15-
```bash
16-
git clone https://github.com/solidjs/solid-start.git
17-
cd solid-start
18-
```
16+
If there's a new feature you'd like to request you can:
1917

20-
2. Enable the correct pnpm version specified in package.json
18+
1. Create an issue and make your pitch. Be sure to explain the value proposition in a way that will benefit most users.
2119

22-
```bash
23-
corepack enable
24-
```
20+
2. If it's a more general concept, feel free to open a [Discussion](https://github.com/solidjs/solid-start/discussions) in the **Idea** category.
2521

26-
3. Install dependencies
22+
A new **primitive** follows the same criteria as issues, please create an issue for it to be discussed before hand.
2723

28-
```bash
29-
pnpm install
30-
```
24+
Primitives that depend on multiple external dependencies and 3rd party integrations are generally not a good fit to live inside this monorepo, we still welcome you to create it and share with the ecosystem.
25+
Reach out in a [Discussion](https://github.com/solidjs/solid-start/discussions) in the **showcase** session and we'll amplify as much as we can!
3126

32-
4. Build all packages and the landing page
33-
```bash
34-
pnpm run build:all
35-
```
27+
## Found a Bug
3628

37-
If you encounter issues (e.g. missing `node_modules`), clean the workspace
29+
If you believe you found a bug, we appreciate you creating an issue.
30+
Issues without a reproduction or PR link will be **automatically closed**.
3831

39-
```bash
40-
pnpm run clean:all
41-
```
32+
To speed up triaging, we recommend 2 strategies:
4233

43-
Then reinstall dependencies and rebuild.
34+
### Minimal Reproduction
4435

45-
## Monorepo Structure
36+
Create a **minimal** reproduction either in a remote IDE or in an open-source repository and add a link to your issue.
4637

47-
SolidStart is a pnpm-based monorepo with nested workspaces. Key directories include
38+
We recommend using the `create-solid` package with the **basic** setting.
4839

49-
- **`packages/start`**: The core `@solidjs/start` package.
50-
- **`apps/landing-page`**: The official landing page.
51-
- **`apps/tests`**: Unit and end-to-end (E2E) tests using Vitest and Cypress.
52-
- **`apps/fixtures`**: Fixture projects for testing.
40+
| Package Manager | Command |
41+
| --------------- | ------------------------------------------ |
42+
| pnpm | `pnpm create solid -s -t basic` |
43+
| npm | `npm create solid -s -t basic` |
44+
| yarn | `yarn create solid -s -t basic` |
45+
| bun | `bun create solid -s -t basic` |
46+
| deno | `deno run -A npm:create-solid -s -t basic` |
5347

54-
Use pnpm filters (e.g. `pnpm --filter @solidjs/start ...`) to target specific packages.
48+
### Failing Test PR
5549

56-
## Developing and Testing Changes
50+
You can also fork this repository and go to `apps/tests`.
51+
There we have an app with all default configurations and many routes.
52+
Create a new route, a Cypress assertion to it and open a PR with the failing test-case.
5753

58-
1. Make your changes in the relevant package (e.g. `packages/start`)
54+
Once the PR is there, **create an issue** and link the PR (mention the PR as you'd mention a person in the issue description and vice-versa).
5955

60-
2. Rebuild affected packages
56+
> [!IMPORTANT]
57+
> Mark the **allow edit by the maintainers** so we can more easily investigate the failing test and propose a fix. Otherwise we may need to close your PR and cherry-pick your commit.
6158
62-
```bash
63-
pnpm run packages:build
64-
```
59+
---
6560

66-
For a full rebuild: `pnpm run build:all`
67-
68-
3. Test your changes
69-
70-
- For fixtures, pick the name of the fixture and run the `dev` with workspace filtering.
71-
```bash
72-
pnpm --filter fixture-basic dev
73-
```
74-
- For the landing page (from the root directory)
75-
```bash
76-
pnpm run lp:dev
77-
```
78-
79-
4. Clean builds if needed
80-
```bash
81-
pnpm run packages:clean # Cleans packages' node_modules and dist folders
82-
pnpm run lp:clean # Cleans the landing page
83-
pnpm run clean:root # Cleans root-level caches
84-
```
85-
86-
## Running Tests
87-
88-
End-to-end tests are located in `apps/tests` projects. For manual testing and development there's the `apps/fixtures` apps, and finally, integration and unit tests live inside their respective packages.
89-
90-
1. Install the Cypress binary (required only once)
91-
92-
```bash
93-
pnpm --filter tests exec cypress install
94-
```
95-
96-
2. For unit tests that check build artifacts, build the test app first
97-
98-
```bash
99-
pnpm --filter tests run build
100-
```
101-
102-
3. Run unit tests
103-
104-
```bash
105-
pnpm --filter tests run unit
106-
```
107-
108-
- CI mode (run once): `pnpm --filter tests run unit:ci`
109-
- UI mode: `pnpm --filter tests run unit:ui`
110-
111-
4. Run E2E tests
112-
113-
```bash
114-
pnpm --filter tests run tests:run
115-
```
116-
117-
- Interactive mode: `pnpm --filter tests run tests:open`
118-
- With dev server: `pnpm --filter tests run tests`
119-
120-
5. Clean test artifacts
121-
```bash
122-
pnpm run clean:test
123-
```
61+
If you have read all the way here, you're already a champ! 🏆
62+
Thank you.

‎README.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,128 @@
1313
- For contributing to codebase, check [CONTRIBUTING.md](/CONTRIBUTING.md)
1414
- For creating a new template, please head on to [solidjs/templates](https://github.com/solidjs/templates)
1515
- For instructions on building with SolidStart, check the [package README.md](/packages/start/README.md) and our [official docs](https://docs.solidjs.com/solid-start)
16+
17+
## Prerequisites
18+
19+
- **Node.js**: Use the version specified in `.nvmrc`, to manage multiple versions across your system, we recommend a version manager such as [fnm](https://github.com/Schniz/fnm), or another of your preference.
20+
- **pnpm**: Install globally via `npm install -g pnpm`. Or let **Corepack** handle it in the setup step below.
21+
- **Git**: Ensure Git is installed for cloning and managing the repository
22+
23+
## Monorepo Structure
24+
25+
SolidStart is a pnpm-based monorepo with nested workspaces. Key directories include
26+
27+
- **`packages/start`**: The core `@solidjs/start` package.
28+
- **`apps/landing-page`**: The official landing page.
29+
- **`apps/tests`**: Unit and end-to-end (E2E) tests using Vitest and Cypress.
30+
- **`apps/fixtures`**: Fixture projects for testing.
31+
32+
Use pnpm filters (e.g. `pnpm --filter @solidjs/start ...`) to target specific packages.
33+
34+
## Local Setup
35+
36+
1. Clone the repository
37+
38+
```bash
39+
git clone https://github.com/solidjs/solid-start.git
40+
cd solid-start
41+
```
42+
43+
2. Enable the correct pnpm version specified in package.json
44+
45+
```bash
46+
corepack enable
47+
```
48+
49+
3. Install dependencies
50+
51+
```bash
52+
pnpm install
53+
```
54+
55+
4. Build all packages and the landing page
56+
```bash
57+
pnpm run build:all
58+
```
59+
60+
If you encounter issues (e.g. missing `node_modules`), clean the workspace
61+
62+
```bash
63+
pnpm run clean:all
64+
```
65+
66+
Then reinstall dependencies and rebuild.
67+
68+
## Running Tests
69+
70+
End-to-end tests are located in `apps/tests` projects. For manual testing and development there's the `apps/fixtures` apps, and finally, integration and unit tests live inside their respective packages.
71+
72+
1. Install the Cypress binary (required only once)
73+
74+
```bash
75+
pnpm --filter tests exec cypress install
76+
```
77+
78+
2. For unit tests that check build artifacts, build the test app first
79+
80+
```bash
81+
pnpm --filter tests run build
82+
```
83+
84+
3. Run unit tests
85+
86+
```bash
87+
pnpm --filter tests run unit
88+
```
89+
90+
- CI mode (run once): `pnpm --filter tests run unit:ci`
91+
- UI mode: `pnpm --filter tests run unit:ui`
92+
93+
4. Run E2E tests
94+
95+
```bash
96+
pnpm --filter tests run tests:run
97+
```
98+
99+
- Interactive mode: `pnpm --filter tests run tests:open`
100+
- With dev server: `pnpm --filter tests run tests`
101+
102+
5. Clean test artifacts
103+
```bash
104+
pnpm run clean:test
105+
```
106+
107+
## Development
108+
109+
1. Make your changes in the relevant package (e.g. `packages/start`)
110+
111+
2. Rebuild affected packages
112+
113+
```bash
114+
pnpm run packages:build
115+
```
116+
117+
For a full rebuild: `pnpm run build:all`
118+
119+
3. Test your changes
120+
121+
- For fixtures, pick the name of the fixture and run the `dev` with workspace filtering.
122+
```bash
123+
pnpm --filter fixture-basic dev
124+
```
125+
- For the landing page (from the root directory)
126+
```bash
127+
pnpm run lp:dev
128+
```
129+
130+
4. Clean builds if needed
131+
```bash
132+
pnpm run packages:clean # Cleans packages' node_modules and dist folders
133+
pnpm run lp:clean # Cleans the landing page
134+
pnpm run clean:root # Cleans root-level caches
135+
```
136+
137+
---
138+
139+
If you have read all the way here, you're already a champ! 🏆
140+
Thank you.

0 commit comments

Comments
 (0)