Skip to content

Commit 9045a17

Browse files
KocalKocal
committed
minor #3161 [Toolkit] Add CONTRIBUTING.md (Kocal)
This PR was squashed before being merged into the 2.x branch. Discussion ---------- [Toolkit] Add CONTRIBUTING.md | Q | A | -------------- | --- | Bug fix? | no | New feature? | no <!-- please update src/**/CHANGELOG.md files --> | Deprecations? | no <!-- if yes, also update UPGRADE-*.md and src/**/CHANGELOG.md --> | Documentation? | yes <!-- required for new features, or documentation updates --> | Issues | Fix #... <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead --> | License | MIT <!-- Replace this notice by a description of your feature/bugfix. This will help reviewers and should be a good start for the documentation. Additionally (see https://symfony.com/releases): - Always add tests and ensure they pass. - For new features, provide some code snippets to help understand usage. - Features and deprecations must be submitted against branch main. - Update/add documentation as required (we can help!) - Changelog entry should follow https://symfony.com/doc/current/contributing/code/conventions.html#writing-a-changelog-entry - Never break backward compatibility (see https://symfony.com/bc). --> Following #3144 (comment) Commits ------- 379e09c [Toolkit] Add CONTRIBUTING.md
2 parents 7c4f5e6 + 379e09c commit 9045a17

File tree

2 files changed

+133
-41
lines changed

2 files changed

+133
-41
lines changed

‎CONTRIBUTING.md‎

Lines changed: 57 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@ Thank you for considering contributing to Symfony UX!
55
Symfony UX is an open source, community-driven project, and we are happy to receive contributions from the community!
66

77
> [!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
99
1010
## Reporting an issue
1111

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).
1313

1414
Please provide as much information as possible,
1515
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.
1717

1818
## Contributing to the code and documentation
1919

@@ -22,11 +22,15 @@ Thanks for your interest in contributing to Symfony UX! Here are some guidelines
2222
### Forking the repository
2323

2424
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).
2626

2727
After forking the repository, you can clone it to your local machine:
2828

2929
```shell
30+
# With GitHub CLI https://cli.github.com/
31+
$ gh repo clone <USERNAME>/symfony-ux symfony-ux
32+
33+
# Using SSH
3034
$ git clone [email protected]:<USERNAME>/symfony-ux.git symfony-ux
3135
$ cd symfony-ux
3236
# Add the upstream repository, to keep your fork up-to-date
@@ -37,16 +41,19 @@ $ git remote add upstream [email protected]:symfony/ux.git
3741

3842
To set up the development environment, you need the following tools:
3943

40-
- [PHP](https://www.php.net/downloads.php) 8.1 or higher
41-
- [Composer](https://getcomposer.org/download/)
42-
- [Node.js](https://nodejs.org/en/download/package-manager) 22.18 or higher
43-
- [Corepack](https://github.com/nodejs/corepack)
44-
- [PNPM](https://pnpm.io/) 10.13 or higher
44+
- **[PHP](https://www.php.net/downloads.php) 8.1 or higher** - Required for running Symfony components
45+
- **[Composer](https://getcomposer.org/download/)** - PHP dependency manager
46+
- **[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)
4549

4650
With these tools installed, you can install the project dependencies:
4751

4852
```shell
53+
# Install root PHP dependencies
4954
$ composer install
55+
56+
# Enable PNPM through Corepack, and install JavaScript dependencies
5057
$ corepack enable && pnpm install
5158
```
5259

@@ -73,33 +80,36 @@ runnable with `php vendor/bin/simple-phpunit`.
7380
### Working with assets
7481

7582
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).
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)
8087

8188
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
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
9097

9198
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
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.
98108
99109
#### Working with Unit tests
100110

101111
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,
112+
and test files are located in the `assets/test/unit/` directory of each UX package,
103113
for example: `src/Vue/assets/test/unit/render_controller.test.ts`.
104114

105115
**Running tests:**
@@ -109,37 +119,43 @@ for example: `src/Vue/assets/test/unit/render_controller.test.ts`.
109119
- `pnpm run test:unit`: runs the unit tests for the package
110120

111121
> [!IMPORTANT]
112-
> 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
113123
> (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.
124+
> Thus it may take some time to run, and **we don't recommend using watch mode**.
115125
116126
#### Working with End-to-End (E2E) tests
117127

118128
> [!NOTE]
119129
> E2E tests simulate real user interactions in a browser, to ensure that the
120130
> UX packages work as expected in a real-world scenario.
121131
122-
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,
123133
and a dedicated Symfony application located in the [`apps/e2e/`](./apps/e2e/) directory,
124-
which contains many examples of Symfony UX packages usage.
134+
which contains many examples of Symfony UX package usages.
125135

126-
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,
127137
for example: `src/Vue/assets/test/browser/vue.test.ts`.
128138

129139
**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,
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
132142

133143
**Running tests:**
134144
- 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
145+
- `pnpm run test:browser`: runs the browser tests for **all** UX packages using a headless browser
136146
- 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
147+
- `pnpm run test:browser`: runs browser tests for the package using a headless browser
138148
- `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
139149

140150
> [!IMPORTANT]
141151
> 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.
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:
156+
> ```shell
157+
> $ pnpm run test:browser:ui
158+
> ```
143159
144160
### Working on documentation
145161
@@ -156,17 +172,17 @@ command from the root directory of the project:
156172
docker run --rm -it -e DOCS_DIR='/docs' -v ${PWD}:/docs oskarstark/doctor-rst -vvv
157173
```
158174
159-
## Useful Git commands
175+
## Useful commands
160176

161-
1. To keep your fork up-to-date with the upstream repository and `2.x` branch, you can run the following commands:
177+
To keep your fork up-to-date with the upstream repository and `2.x` branch:
162178
```shell
163179
$ git checkout 2.x && \
164180
git fetch upstream && \
165181
git reset --hard upstream/2.x && \
166182
git push origin 2.x
167183
```
168184

169-
2. To rebase your branch on top of the `2.x` branch, you can run the following commands:
185+
To rebase your branch on top of the `2.x` branch:
170186
```shell
171187
$ git checkout my-feature-branch && \
172188
git rebase upstream/2.x && \

‎src/Toolkit/CONTRIBUTING.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Contributing
2+
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.
4+
5+
## Setting up the development environment
6+
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.
8+
9+
Then, install the UX Toolkit dependencies:
10+
```shell
11+
# src/Toolkit
12+
composer install
13+
```
14+
15+
## Previewing kits
16+
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).
18+
19+
Then, run the following commands from the `ux.symfony.com/` directory:
20+
```shell
21+
# Link local UX packages
22+
php ../link
23+
24+
# Run the local web server
25+
symfony serve -d
26+
```
27+
28+
When the server is running, you can access:
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
32+
33+
## Kit structure
34+
35+
A kit is composed of several recipes, each providing Twig components, styles, and JavaScript.
36+
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
39+
3. Each kit directory contains:
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
50+
51+
## Working with kits
52+
53+
After setting up your development environment and the UX Website locally, you can start modifying the kits and testing them.
54+
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.
56+
You can then preview your changes by navigating to the relevant sections in the UX Website.
57+
58+
### Running tests & snapshots
59+
60+
Tests use snapshots to ensure that the kits and their recipes work as expected and to prevent regressions.
61+
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.
63+
64+
The rendered output is then compared to stored snapshots to ensure that the kit's recipes work as expected.
65+
66+
To update the snapshots, run the following command from the `src/Toolkit/` directory:
67+
```shell
68+
# Remove existing snapshots (may be useful if some Twig code examples were removed)
69+
rm -fr tests/Functional/__snapshots__
70+
71+
# Run tests and update snapshots
72+
php vendor/bin/simple-phpunit -d --update-snapshots
73+
74+
# Add the updated snapshots to git
75+
git add tests/Functional/__snapshots__
76+
```

0 commit comments

Comments
 (0)