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
+73-45Lines changed: 73 additions & 45 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,15 +5,15 @@ Thank you for considering contributing to Symfony UX!
5
5
Symfony UX is an open source, community-driven project, and we are happy to receive contributions from the community!
6
6
7
7
> [!TIP]
8
-
> It's a good idea to read the [Symfony's Contribution Guide](https://symfony.com/doc/current/contributing/index.html) first, even if not all of it applies to Symfony UX and should be adapted to this project (e.g.: Symfony UX has only one base branch, `2.x`).
8
+
> It's a good idea to read the [Symfony's Contribution Guide](https://symfony.com/doc/current/contributing/index.html) first
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,11 +22,15 @@ 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:
> Snapshots will not reflect changes if you forget to update the EXAMPLES.md.
91
+
73
92
### Working with assets
74
93
75
94
Assets are specific to each Symfony UX package:
76
-
- They are located in the `assets/` directory of each package, and can be either TypeScript or CSS files, respectively compiled through Rollup and PostCSS,
77
-
- Assets are mentioned in the `package.json` file of each package,
78
-
- Assets **must be** compiled before committing changes,
79
-
- 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).
95
+
- 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)
96
+
- Assets are mentioned in the `package.json` file of each package
97
+
- Assets **must be** compiled before committing changes
98
+
- 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)
80
99
81
100
To help you with assets, you can run the following commands in a specific package directory (e.g., `src/Map/assets/`):
82
-
-`pnpm run build`: build (compile) assets from the package,
83
-
-`pnpm run watch`: watch for modifications and rebuild assets from the package,
84
-
-`pnpm run test`: run the tests from the package,
85
-
-`pnpm run test:unit`: run the Unit tests from the package,
86
-
-`pnpm run test:browser`: run the Browser tests from the package, in a headless browser
87
-
-`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
88
-
-`pnpm run check`: run the formatter, linter, and sort imports, and fails if any modifications
89
-
-`pnpm run check --write`: run the formatter, linter, imports sorting, and write modifications
101
+
-`pnpm run build`: build (compile) assets from the package
102
+
-`pnpm run watch`: watch for modifications and rebuild assets from the package
103
+
-`pnpm run test`: run the tests from the package
104
+
-`pnpm run test:unit`: run the unit tests from the package
105
+
-`pnpm run test:browser`: run the browser tests from the package in a headless browser
106
+
-`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
107
+
-`pnpm run check`: run the formatter, linter, and sort imports, and fail if any modifications are needed
108
+
-`pnpm run check --write`: run the formatter, linter, and import sorting, and write modifications
90
109
91
110
Thanks to [PNPM Workspaces](https://pnpm.io/workspaces), you can also run these commands from the root directory of the project:
92
-
-`pnpm run build`: build (compile) assets from **all** packages,
93
-
-`pnpm run test`: run the tests from **all** packages,
94
-
-`pnpm run test:unit`: run the Unit tests from **all** packages,
95
-
-`pnpm run test:browser`: run the Browser tests from **all** packages, in a headless browser
96
-
-`pnpm run check`: run the formatter, linter, and sort imports for **all** packages, and fails if any modifications
97
-
-`pnpm run check --write`: run the formatter, linter, imports sorting for **all** packages, and write modifications
111
+
-`pnpm run build`: build (compile) assets from **all** packages
112
+
-`pnpm run test`: run the tests from **all** packages
113
+
-`pnpm run test:unit`: run the unit tests from **all** packages
114
+
-`pnpm run test:browser`: run the browser tests from **all** packages in a headless browser
115
+
-`pnpm run check`: run the formatter, linter, and sort imports for **all** packages, and fail if any modifications are needed
116
+
-`pnpm run check --write`: run the formatter, linter, and import sorting for **all** packages, and write modifications
117
+
118
+
> [!IMPORTANT]
119
+
> Always run `pnpm run build` before committing your changes to ensure assets are properly compiled.
98
120
99
121
#### Working with Unit tests
100
122
101
123
We use [Vitest](https://vitest.dev/) for unit testing of the assets,
102
-
and tests files are located in the `assets/test/unit/` directory of each UX package,
124
+
and test files are located in the `assets/test/unit/` directory of each UX package,
103
125
for example: `src/Vue/assets/test/unit/render_controller.test.ts`.
104
126
105
127
**Running tests:**
@@ -109,37 +131,43 @@ for example: `src/Vue/assets/test/unit/render_controller.test.ts`.
109
131
-`pnpm run test:unit`: runs the unit tests for the package
110
132
111
133
> [!IMPORTANT]
112
-
> The command `pnpm run test:unit`ensure that each possible combination of dependencies is tested
134
+
> The command `pnpm run test:unit`ensures that each possible combination of dependencies is tested
113
135
> (e.g., `"chart.js": "^3.4.1 || ^4.0"` for UX Chartjs).
114
-
> Thus it may take some time to run, and it may be not recommended to use watch mode.
136
+
> Thus it may take some time to run, and **we don't recommend using watch mode**.
115
137
116
138
#### Working with End-to-End (E2E) tests
117
139
118
140
> [!NOTE]
119
141
> E2E tests simulate real user interactions in a browser, to ensure that the
120
142
> UX packages work as expected in a real-world scenario.
121
143
122
-
Symfony UX use[Playwright](https://playwright.dev/) for browser automation and testing,
144
+
Symfony UX uses[Playwright](https://playwright.dev/) for browser automation and testing,
123
145
and a dedicated Symfony application located in the [`apps/e2e/`](./apps/e2e/) directory,
124
-
which contains many examples of Symfony UX packages usage.
146
+
which contains many examples of Symfony UX package usages.
125
147
126
-
Tests files are located in the `assets/test/browser/` directory of each UX package,
148
+
Test files are located in the `assets/test/browser/` directory of each UX package,
127
149
for example: `src/Vue/assets/test/browser/vue.test.ts`.
128
150
129
151
**Setup:**
130
-
1. Ensure to have followed the steps in the [Setting up the development environment](#setting-up-the-development-environment) section
131
-
2. Read and follow the instructions in the [`apps/e2e/README.md`](./apps/e2e/README.md) file,
152
+
1. Ensure you have followed the steps in the [Setting up the development environment](#setting-up-the-development-environment) section
153
+
2. Read and follow the instructions in the [`apps/e2e/README.md`](./apps/e2e/README.md) file
132
154
133
155
**Running tests:**
134
156
- At the project's root, you can run the following commands:
135
-
-`pnpm run test:browser`: runs the browser tests for **all** UX packages, using a headless browser
157
+
-`pnpm run test:browser`: runs the browser tests for **all** UX packages using a headless browser
136
158
- Inside the `assets/` directory of each UX package, you can run the following commands:
137
-
-`pnpm run test:browser`: runs browser tests for the package, using a headless browser
159
+
-`pnpm run test:browser`: runs browser tests for the package using a headless browser
138
160
-`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
139
161
140
162
> [!IMPORTANT]
141
163
> Due to their nature, E2E tests may be slower to run than unit tests.
142
-
> During the development, we recommend to run `pnpm run test:browser` or `pnpm run test:browser:ui` for a specific UX package.
164
+
> During development, we recommend running `pnpm run test:browser` or `pnpm run test:browser:ui` for a specific UX package.
165
+
166
+
> [!TIP]
167
+
> If tests are failing locally, try running them in headed mode to see what's happening:
168
+
> ```shell
169
+
> $ pnpm run test:browser:ui
170
+
>```
143
171
144
172
### Working on documentation
145
173
@@ -156,19 +184,19 @@ command from the root directory of the project:
156
184
docker run --rm -it -e DOCS_DIR='/docs' -v ${PWD}:/docs oskarstark/doctor-rst -vvv
157
185
```
158
186
159
-
## Useful Git commands
187
+
## Useful commands
160
188
161
-
1.To keep your fork up-to-date with the upstream repository and `2.x` branch, you can run the following commands:
189
+
To keep your fork up-to-date with the upstream repository and `2.x` branch:
162
190
```shell
163
-
$ git checkout 2.x && \
191
+
$ git checkout 3.x && \
164
192
git fetch upstream && \
165
-
git reset --hard upstream/2.x && \
166
-
git push origin 2.x
193
+
git reset --hard upstream/3.x && \
194
+
git push origin 3.x
167
195
```
168
196
169
-
2.To rebase your branch on top of the `2.x` branch, you can run the following commands:
0 commit comments