You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+46-37Lines changed: 46 additions & 37 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,11 +9,11 @@ Symfony UX is an open source, community-driven project, and we are happy to rece
9
9
10
10
## Reporting an issue
11
11
12
-
If you either find a bug, have a feature request, or need help/have a question, please [open an issue](https://github.com/symfony/ux/issues/new/choose).
12
+
If you find a bug, have a feature request, or need help/have a question, please [open an issue](https://github.com/symfony/ux/issues/new/choose).
13
13
14
14
Please provide as much information as possible,
15
15
and remember to follow our [Code of Conduct](https://symfony.com/doc/current/contributing/code_of_conduct/index.html)
16
-
as well, to ensure a friendly environment for all contributors.
16
+
to ensure a friendly environment for all contributors.
17
17
18
18
## Contributing to the code and documentation
19
19
@@ -22,7 +22,7 @@ Thanks for your interest in contributing to Symfony UX! Here are some guidelines
22
22
### Forking the repository
23
23
24
24
To contribute to Symfony UX, you need to [fork the **symfony/ux** repository](https://github.com/symfony/ux/fork) on GitHub.
25
-
This will give you a copy of the code under your GitHub user account, read[the documentation "How to fork a repository"](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
25
+
This will give you a copy of the code under your GitHub user account. Read[the documentation "How to fork a repository"](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
26
26
27
27
After forking the repository, you can clone it to your local machine:
-**[Node.js](https://nodejs.org/en/download/package-manager) 22.18 or higher** - Required for asset compilation
47
+
-**[Corepack](https://github.com/nodejs/corepack)** - Package manager manager (comes with Node.js 16+)
48
+
-**[PNPM](https://pnpm.io/) 10.16.1 or higher** - JavaScript package manager (installed via Corepack)
49
49
50
50
With these tools installed, you can install the project dependencies:
51
51
@@ -80,33 +80,36 @@ runnable with `php vendor/bin/simple-phpunit`.
80
80
### Working with assets
81
81
82
82
Assets are specific to each Symfony UX package:
83
-
- They are located in the `assets/` directory of each package, and can be either TypeScript or CSS files, all compiled through [tsup](https://github.com/egoist/tsup),
84
-
- Assets are mentioned in the `package.json` file of each package,
85
-
- Assets **must be** compiled before committing changes,
86
-
- Assets **must be** compatible with the [Symfony AssetMapper](https://symfony.com/doc/current/frontend/asset_mapper.html) and [Symfony Webpack Encore](https://symfony.com/doc/current/frontend/encore/index.html).
83
+
- They are located in the `assets/` directory of each package and can be either TypeScript or CSS files, all compiled through [tsup](https://github.com/egoist/tsup)
84
+
- Assets are mentioned in the `package.json` file of each package
85
+
- Assets **must be** compiled before committing changes
86
+
- Assets **must be** compatible with the [Symfony AssetMapper](https://symfony.com/doc/current/frontend/asset_mapper.html) and [Symfony Webpack Encore](https://symfony.com/doc/current/frontend/encore/index.html)
87
87
88
88
To help you with assets, you can run the following commands in a specific package directory (e.g., `src/Map/assets/`):
89
-
-`pnpm run build`: build (compile) assets from the package,
90
-
-`pnpm run watch`: watch for modifications and rebuild assets from the package,
91
-
-`pnpm run test`: run the tests from the package,
92
-
-`pnpm run test:unit`: run the Unit tests from the package,
93
-
-`pnpm run test:browser`: run the Browser tests from the package, in a headless browser
94
-
-`pnpm run test:browser:ui`: run the Browser tests from the package in interactive mode, allowing you to see the tests running in a browser window and debug them if needed
95
-
-`pnpm run check`: run the formatter, linter, and sort imports, and fails if any modifications
96
-
-`pnpm run check --write`: run the formatter, linter, imports sorting, and write modifications
89
+
-`pnpm run build`: build (compile) assets from the package
90
+
-`pnpm run watch`: watch for modifications and rebuild assets from the package
91
+
-`pnpm run test`: run the tests from the package
92
+
-`pnpm run test:unit`: run the unit tests from the package
93
+
-`pnpm run test:browser`: run the browser tests from the package in a headless browser
94
+
-`pnpm run test:browser:ui`: run the browser tests from the package in interactive mode, allowing you to see the tests running in a browser window and debug them if needed
95
+
-`pnpm run check`: run the formatter, linter, and sort imports, and fail if any modifications are needed
96
+
-`pnpm run check --write`: run the formatter, linter, and import sorting, and write modifications
97
97
98
98
Thanks to [PNPM Workspaces](https://pnpm.io/workspaces), you can also run these commands from the root directory of the project:
99
-
-`pnpm run build`: build (compile) assets from **all** packages,
100
-
-`pnpm run test`: run the tests from **all** packages,
101
-
-`pnpm run test:unit`: run the Unit tests from **all** packages,
102
-
-`pnpm run test:browser`: run the Browser tests from **all** packages, in a headless browser
103
-
-`pnpm run check`: run the formatter, linter, and sort imports for **all** packages, and fails if any modifications
104
-
-`pnpm run check --write`: run the formatter, linter, imports sorting for **all** packages, and write modifications
99
+
-`pnpm run build`: build (compile) assets from **all** packages
100
+
-`pnpm run test`: run the tests from **all** packages
101
+
-`pnpm run test:unit`: run the unit tests from **all** packages
102
+
-`pnpm run test:browser`: run the browser tests from **all** packages in a headless browser
103
+
-`pnpm run check`: run the formatter, linter, and sort imports for **all** packages, and fail if any modifications are needed
104
+
-`pnpm run check --write`: run the formatter, linter, and import sorting for **all** packages, and write modifications
105
+
106
+
> [!IMPORTANT]
107
+
> Always run `pnpm run build` before committing your changes to ensure assets are properly compiled.
105
108
106
109
#### Working with Unit tests
107
110
108
111
We use [Vitest](https://vitest.dev/) for unit testing of the assets,
109
-
and tests files are located in the `assets/test/unit/` directory of each UX package,
112
+
and test files are located in the `assets/test/unit/` directory of each UX package,
110
113
for example: `src/Vue/assets/test/unit/render_controller.test.ts`.
111
114
112
115
**Running tests:**
@@ -116,37 +119,43 @@ for example: `src/Vue/assets/test/unit/render_controller.test.ts`.
116
119
-`pnpm run test:unit`: runs the unit tests for the package
117
120
118
121
> [!IMPORTANT]
119
-
> The command `pnpm run test:unit`ensure that each possible combination of dependencies is tested
122
+
> The command `pnpm run test:unit`ensures that each possible combination of dependencies is tested
120
123
> (e.g., `"chart.js": "^3.4.1 || ^4.0"` for UX Chartjs).
121
-
> Thus it may take some time to run, and **we don't recommend to use watch mode**.
124
+
> Thus it may take some time to run, and **we don't recommend using watch mode**.
122
125
123
126
#### Working with End-to-End (E2E) tests
124
127
125
128
> [!NOTE]
126
129
> E2E tests simulate real user interactions in a browser, to ensure that the
127
130
> UX packages work as expected in a real-world scenario.
128
131
129
-
Symfony UX use[Playwright](https://playwright.dev/) for browser automation and testing,
132
+
Symfony UX uses[Playwright](https://playwright.dev/) for browser automation and testing,
130
133
and a dedicated Symfony application located in the [`apps/e2e/`](./apps/e2e/) directory,
131
-
which contains many examples of Symfony UX packages usage.
134
+
which contains many examples of Symfony UX package usages.
132
135
133
-
Tests files are located in the `assets/test/browser/` directory of each UX package,
136
+
Test files are located in the `assets/test/browser/` directory of each UX package,
134
137
for example: `src/Vue/assets/test/browser/vue.test.ts`.
135
138
136
139
**Setup:**
137
-
1. Ensure to have followed the steps in the [Setting up the development environment](#setting-up-the-development-environment) section
138
-
2. Read and follow the instructions in the [`apps/e2e/README.md`](./apps/e2e/README.md) file,
140
+
1. Ensure you have followed the steps in the [Setting up the development environment](#setting-up-the-development-environment) section
141
+
2. Read and follow the instructions in the [`apps/e2e/README.md`](./apps/e2e/README.md) file
139
142
140
143
**Running tests:**
141
144
- At the project's root, you can run the following commands:
142
-
-`pnpm run test:browser`: runs the browser tests for **all** UX packages, using a headless browser
145
+
-`pnpm run test:browser`: runs the browser tests for **all** UX packages using a headless browser
143
146
- Inside the `assets/` directory of each UX package, you can run the following commands:
144
-
-`pnpm run test:browser`: runs browser tests for the package, using a headless browser
147
+
-`pnpm run test:browser`: runs browser tests for the package using a headless browser
145
148
-`pnpm run test:browser:ui`: runs the browser tests in interactive mode, allowing you to see the tests running in a browser window and debug them if needed
146
149
147
150
> [!IMPORTANT]
148
151
> Due to their nature, E2E tests may be slower to run than unit tests.
149
-
> During the development, we recommend to run `pnpm run test:browser` or `pnpm run test:browser:ui` for a specific UX package.
152
+
> During development, we recommend running `pnpm run test:browser` or `pnpm run test:browser:ui` for a specific UX package.
153
+
154
+
> [!TIP]
155
+
> If tests are failing locally, try running them in headed mode to see what's happening:
Copy file name to clipboardExpand all lines: src/Toolkit/CONTRIBUTING.md
+28-30Lines changed: 28 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,22 +1,20 @@
1
1
# Contributing
2
2
3
-
Due to its nature, the Symfony UX Toolkit requires a specific setup to be able to
4
-
develop and test it properly. Please follow the instructions below to set up your
5
-
development environment.
3
+
Due to its nature, the Symfony UX Toolkit requires a specific setup to develop and test it properly. Please follow the instructions below to set up your development environment.
6
4
7
5
## Setting up the development environment
8
6
9
-
First, ensure to have followed the [Symfony UX's Contribution Guide](https://github.com/symfony/ux/blob/2.x/CONTRIBUTING.md) to set up your fork of the main repository, install dependencies, etc.
7
+
First, ensure you have followed the [Symfony UX's Contribution Guide](https://github.com/symfony/ux/blob/2.x/CONTRIBUTING.md) to set up your fork of the main repository, install dependencies, etc.
10
8
11
-
Then, install UX Toolkit dependencies:
9
+
Then, install the UX Toolkit dependencies:
12
10
```shell
13
11
# src/Toolkit
14
12
composer install
15
13
```
16
14
17
-
## Preview kits
15
+
## Previewing kits
18
16
19
-
For the moment, kits can only be previewed by the Symfony UX Website. installation instructions can be found at[Symfony UX Website's `README.md`](https://github.com/symfony/ux/tree/2.x/ux.symfony.com).
17
+
Currently, kits can only be previewed through the Symfony UX Website. Installation instructions can be found in the[Symfony UX Website's `README.md`](https://github.com/symfony/ux/tree/2.x/ux.symfony.com).
20
18
21
19
Then, run the following commands from the `ux.symfony.com/` directory:
22
20
```shell
@@ -28,46 +26,46 @@ symfony serve -d
28
26
```
29
27
30
28
When the server is running, you can access:
31
-
-the UX Toolkit homepage at https://127.0.0.1:9044/toolkit,
32
-
-the list of available Kits at https://127.0.0.1:9044/toolkit#kits,
33
-
-a dedicated section for each Kit, e.g. https://127.0.0.1:9044/toolkit/kits/shadcn for the Shadcn UI Kit.
29
+
-The UX Toolkit homepage at https://127.0.0.1:9044/toolkit
30
+
-The list of available kits at https://127.0.0.1:9044/toolkit#kits
31
+
-A dedicated section for each kit, e.g.,https://127.0.0.1:9044/toolkit/kits/shadcn for the Shadcn UI Kit
34
32
35
-
## Kit's structure
33
+
## Kit structure
36
34
37
-
A Kit is composed of several Recipes, each providing Twig components, styles, and JavaScript.
35
+
A kit is composed of several recipes, each providing Twig components, styles, and JavaScript.
38
36
39
-
1. Each kit is located in the `src/Toolkit/kits/` directory.
40
-
2. Each kit has its own directory named after the kit, e.g. `shadcn/` for the Shadcn UI Kit.
37
+
1. Each kit is located in the `src/Toolkit/kits/` directory
38
+
2. Each kit has its own directory named after the kit, e.g.,`shadcn/` for the Shadcn UI Kit
41
39
3. Each kit directory contains:
42
-
-a`INSTALL.md` file with installation instructions, it is used by the UX Website,
43
-
-a`manifest.json` file containing metadata about the kit: its name, description, license, homepage, etc.,
44
-
-a folder for each Recipe provided by the kit, e.g. `button/` for the Button Recipe,
45
-
4. Each Recipe directory contains:
46
-
-a`manifest.json` file containing metadata about the Recipe: its type, name, description, files to copy, dependencies, etc.,
47
-
-a`EXAMPLES.md` file with usage examples, it is used by the UX Website.
48
-
-based on the "files to copy" setting, the Kit may contain subdirectories like:
49
-
-`templates/components/` for Twig components,
50
-
-`assets/controllers/` for Stimulus controllers,
51
-
-the "files to copy" structure is flexible, but we recommend to follow the above conventions for consistency accross kits and Symfony apps.
40
+
-An`INSTALL.md` file with installation instructions (used by the UX Website)
41
+
-A`manifest.json` file containing metadata about the kit: its name, description, license, homepage, etc.
42
+
-A folder for each recipe provided by the kit, e.g.,`button/` for the Button recipe
43
+
4. Each recipe directory contains:
44
+
-A`manifest.json` file containing metadata about the recipe: its type, name, description, files to copy, dependencies, etc.
45
+
-An`EXAMPLES.md` file with usage examples (used by the UX Website)
46
+
-Based on the "files to copy" setting, the kit may contain subdirectories such as:
47
+
-`templates/components/` for Twig components
48
+
-`assets/controllers/` for Stimulus controllers
49
+
-The "files to copy" structure is flexible, but we recommend following the above conventions for consistency across kits and Symfony apps
52
50
53
51
## Working with kits
54
52
55
-
After setting up your development environment and the UX Website locally, you can start modifying the kits and test them.
53
+
After setting up your development environment and the UX Website locally, you can start modifying the kits and testing them.
56
54
57
-
Adding new recipes, or modifying existing ones, will be automatically reflected in the UX Website, thanks to the local linking done with the `php link` command.
55
+
Adding new recipes or modifying existing ones will be automatically reflected in the UX Website, thanks to the local linking done with the `php link` command.
58
56
You can then preview your changes by navigating to the relevant sections in the UX Website.
59
57
60
58
### Running tests & snapshots
61
59
62
-
Tests use snapshots to ensure that the kits and their recipes work as expected, and to prevent regressions.
60
+
Tests use snapshots to ensure that the kits and their recipes work as expected and to prevent regressions.
63
61
64
-
Snapshots are created through all Twig code examples provided in each Recipe's `EXAMPLES.md` file. The Twig code examples are rendered in an isolated environment.
62
+
Snapshots are created from all Twig code examples provided in each recipe's `EXAMPLES.md` file. The Twig code examples are rendered in an isolated environment.
65
63
66
-
The rendered output is then compared to stored snapshots to ensure that the Kit's recipes work as expected.
64
+
The rendered output is then compared to stored snapshots to ensure that the kit's recipes work as expected.
67
65
68
66
To update the snapshots, run the following command from the `src/Toolkit/` directory:
69
67
```shell
70
-
# Remove existing snapshots, may be useful if some Twig code examples were removed
68
+
# Remove existing snapshots (may be useful if some Twig code examples were removed)
0 commit comments