From 379e09ca769198e6e59ef49489e68b0b2cf7c3e8 Mon Sep 17 00:00:00 2001 From: Hugo Alliaume Date: Mon, 10 Nov 2025 07:59:31 +0100 Subject: [PATCH] [Toolkit] Add CONTRIBUTING.md --- CONTRIBUTING.md | 98 +++++++++++++++++++++---------------- src/Toolkit/CONTRIBUTING.md | 76 ++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+), 41 deletions(-) create mode 100644 src/Toolkit/CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ea8a360da6..56b0ec2ea74 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,15 +5,15 @@ Thank you for considering contributing to Symfony UX! Symfony UX is an open source, community-driven project, and we are happy to receive contributions from the community! > [!TIP] -> 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`). +> It's a good idea to read the [Symfony's Contribution Guide](https://symfony.com/doc/current/contributing/index.html) first ## Reporting an issue -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). +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). Please provide as much information as possible, and remember to follow our [Code of Conduct](https://symfony.com/doc/current/contributing/code_of_conduct/index.html) -as well, to ensure a friendly environment for all contributors. +to ensure a friendly environment for all contributors. ## Contributing to the code and documentation @@ -22,11 +22,15 @@ Thanks for your interest in contributing to Symfony UX! Here are some guidelines ### Forking the repository To contribute to Symfony UX, you need to [fork the **symfony/ux** repository](https://github.com/symfony/ux/fork) on GitHub. -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). +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). After forking the repository, you can clone it to your local machine: ```shell +# With GitHub CLI https://cli.github.com/ +$ gh repo clone /symfony-ux symfony-ux + +# Using SSH $ git clone git@github.com:/symfony-ux.git symfony-ux $ cd symfony-ux # Add the upstream repository, to keep your fork up-to-date @@ -37,16 +41,19 @@ $ git remote add upstream git@github.com:symfony/ux.git To set up the development environment, you need the following tools: -- [PHP](https://www.php.net/downloads.php) 8.1 or higher -- [Composer](https://getcomposer.org/download/) -- [Node.js](https://nodejs.org/en/download/package-manager) 22.18 or higher -- [Corepack](https://github.com/nodejs/corepack) -- [PNPM](https://pnpm.io/) 10.13 or higher +- **[PHP](https://www.php.net/downloads.php) 8.1 or higher** - Required for running Symfony components +- **[Composer](https://getcomposer.org/download/)** - PHP dependency manager +- **[Node.js](https://nodejs.org/en/download/package-manager) 22.18 or higher** - Required for asset compilation +- **[Corepack](https://github.com/nodejs/corepack)** - Package manager manager (comes with Node.js 16+) +- **[PNPM](https://pnpm.io/) 10.16.1 or higher** - JavaScript package manager (installed via Corepack) With these tools installed, you can install the project dependencies: ```shell +# Install root PHP dependencies $ composer install + +# Enable PNPM through Corepack, and install JavaScript dependencies $ corepack enable && pnpm install ``` @@ -73,33 +80,36 @@ runnable with `php vendor/bin/simple-phpunit`. ### Working with assets Assets are specific to each Symfony UX package: - - They are located in the `assets/` directory of each package, and can be either TypeScript or CSS files, respectively compiled through Rollup and PostCSS, - - Assets are mentioned in the `package.json` file of each package, - - Assets **must be** compiled before committing changes, - - 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). + - 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) + - Assets are mentioned in the `package.json` file of each package + - Assets **must be** compiled before committing changes + - 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) To help you with assets, you can run the following commands in a specific package directory (e.g., `src/Map/assets/`): - - `pnpm run build`: build (compile) assets from the package, - - `pnpm run watch`: watch for modifications and rebuild assets from the package, - - `pnpm run test`: run the tests from the package, - - `pnpm run test:unit`: run the Unit tests from the package, - - `pnpm run test:browser`: run the Browser tests from the package, in a headless browser - - `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 - - `pnpm run check`: run the formatter, linter, and sort imports, and fails if any modifications - - `pnpm run check --write`: run the formatter, linter, imports sorting, and write modifications + - `pnpm run build`: build (compile) assets from the package + - `pnpm run watch`: watch for modifications and rebuild assets from the package + - `pnpm run test`: run the tests from the package + - `pnpm run test:unit`: run the unit tests from the package + - `pnpm run test:browser`: run the browser tests from the package in a headless browser + - `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 + - `pnpm run check`: run the formatter, linter, and sort imports, and fail if any modifications are needed + - `pnpm run check --write`: run the formatter, linter, and import sorting, and write modifications Thanks to [PNPM Workspaces](https://pnpm.io/workspaces), you can also run these commands from the root directory of the project: - - `pnpm run build`: build (compile) assets from **all** packages, - - `pnpm run test`: run the tests from **all** packages, - - `pnpm run test:unit`: run the Unit tests from **all** packages, - - `pnpm run test:browser`: run the Browser tests from **all** packages, in a headless browser - - `pnpm run check`: run the formatter, linter, and sort imports for **all** packages, and fails if any modifications - - `pnpm run check --write`: run the formatter, linter, imports sorting for **all** packages, and write modifications + - `pnpm run build`: build (compile) assets from **all** packages + - `pnpm run test`: run the tests from **all** packages + - `pnpm run test:unit`: run the unit tests from **all** packages + - `pnpm run test:browser`: run the browser tests from **all** packages in a headless browser + - `pnpm run check`: run the formatter, linter, and sort imports for **all** packages, and fail if any modifications are needed + - `pnpm run check --write`: run the formatter, linter, and import sorting for **all** packages, and write modifications + +> [!IMPORTANT] +> Always run `pnpm run build` before committing your changes to ensure assets are properly compiled. #### Working with Unit tests We use [Vitest](https://vitest.dev/) for unit testing of the assets, -and tests files are located in the `assets/test/unit/` directory of each UX package, +and test files are located in the `assets/test/unit/` directory of each UX package, for example: `src/Vue/assets/test/unit/render_controller.test.ts`. **Running tests:** @@ -109,9 +119,9 @@ for example: `src/Vue/assets/test/unit/render_controller.test.ts`. - `pnpm run test:unit`: runs the unit tests for the package > [!IMPORTANT] -> The command `pnpm run test:unit` ensure that each possible combination of dependencies is tested +> The command `pnpm run test:unit` ensures that each possible combination of dependencies is tested > (e.g., `"chart.js": "^3.4.1 || ^4.0"` for UX Chartjs). -> Thus it may take some time to run, and it may be not recommended to use watch mode. +> Thus it may take some time to run, and **we don't recommend using watch mode**. #### Working with End-to-End (E2E) tests @@ -119,27 +129,33 @@ for example: `src/Vue/assets/test/unit/render_controller.test.ts`. > E2E tests simulate real user interactions in a browser, to ensure that the > UX packages work as expected in a real-world scenario. -Symfony UX use [Playwright](https://playwright.dev/) for browser automation and testing, +Symfony UX uses [Playwright](https://playwright.dev/) for browser automation and testing, and a dedicated Symfony application located in the [`apps/e2e/`](./apps/e2e/) directory, -which contains many examples of Symfony UX packages usage. +which contains many examples of Symfony UX package usages. -Tests files are located in the `assets/test/browser/` directory of each UX package, +Test files are located in the `assets/test/browser/` directory of each UX package, for example: `src/Vue/assets/test/browser/vue.test.ts`. **Setup:** -1. Ensure to have followed the steps in the [Setting up the development environment](#setting-up-the-development-environment) section -2. Read and follow the instructions in the [`apps/e2e/README.md`](./apps/e2e/README.md) file, +1. Ensure you have followed the steps in the [Setting up the development environment](#setting-up-the-development-environment) section +2. Read and follow the instructions in the [`apps/e2e/README.md`](./apps/e2e/README.md) file **Running tests:** - At the project's root, you can run the following commands: - - `pnpm run test:browser`: runs the browser tests for **all** UX packages, using a headless browser + - `pnpm run test:browser`: runs the browser tests for **all** UX packages using a headless browser - Inside the `assets/` directory of each UX package, you can run the following commands: - - `pnpm run test:browser`: runs browser tests for the package, using a headless browser + - `pnpm run test:browser`: runs browser tests for the package using a headless browser - `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 > [!IMPORTANT] > Due to their nature, E2E tests may be slower to run than unit tests. -> During the development, we recommend to run `pnpm run test:browser` or `pnpm run test:browser:ui` for a specific UX package. +> During development, we recommend running `pnpm run test:browser` or `pnpm run test:browser:ui` for a specific UX package. + +> [!TIP] +> If tests are failing locally, try running them in headed mode to see what's happening: +> ```shell +> $ pnpm run test:browser:ui +> ``` ### Working on documentation @@ -156,9 +172,9 @@ command from the root directory of the project: docker run --rm -it -e DOCS_DIR='/docs' -v ${PWD}:/docs oskarstark/doctor-rst -vvv ``` -## Useful Git commands +## Useful commands -1. To keep your fork up-to-date with the upstream repository and `2.x` branch, you can run the following commands: +To keep your fork up-to-date with the upstream repository and `2.x` branch: ```shell $ git checkout 2.x && \ git fetch upstream && \ @@ -166,7 +182,7 @@ $ git checkout 2.x && \ git push origin 2.x ``` -2. To rebase your branch on top of the `2.x` branch, you can run the following commands: +To rebase your branch on top of the `2.x` branch: ```shell $ git checkout my-feature-branch && \ git rebase upstream/2.x && \ diff --git a/src/Toolkit/CONTRIBUTING.md b/src/Toolkit/CONTRIBUTING.md new file mode 100644 index 00000000000..c31cf6da913 --- /dev/null +++ b/src/Toolkit/CONTRIBUTING.md @@ -0,0 +1,76 @@ +# Contributing + +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. + +## Setting up the development environment + +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. + +Then, install the UX Toolkit dependencies: +```shell +# src/Toolkit +composer install +``` + +## Previewing kits + +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). + +Then, run the following commands from the `ux.symfony.com/` directory: +```shell +# Link local UX packages +php ../link + +# Run the local web server +symfony serve -d +``` + +When the server is running, you can access: +- The UX Toolkit homepage at https://127.0.0.1:9044/toolkit +- The list of available kits at https://127.0.0.1:9044/toolkit#kits +- A dedicated section for each kit, e.g., https://127.0.0.1:9044/toolkit/kits/shadcn for the Shadcn UI Kit + +## Kit structure + +A kit is composed of several recipes, each providing Twig components, styles, and JavaScript. + +1. Each kit is located in the `src/Toolkit/kits/` directory +2. Each kit has its own directory named after the kit, e.g., `shadcn/` for the Shadcn UI Kit +3. Each kit directory contains: + - An `INSTALL.md` file with installation instructions (used by the UX Website) + - A `manifest.json` file containing metadata about the kit: its name, description, license, homepage, etc. + - A folder for each recipe provided by the kit, e.g., `button/` for the Button recipe +4. Each recipe directory contains: + - A `manifest.json` file containing metadata about the recipe: its type, name, description, files to copy, dependencies, etc. + - An `EXAMPLES.md` file with usage examples (used by the UX Website) + - Based on the "files to copy" setting, the kit may contain subdirectories such as: + - `templates/components/` for Twig components + - `assets/controllers/` for Stimulus controllers + - The "files to copy" structure is flexible, but we recommend following the above conventions for consistency across kits and Symfony apps + +## Working with kits + +After setting up your development environment and the UX Website locally, you can start modifying the kits and testing them. + +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. +You can then preview your changes by navigating to the relevant sections in the UX Website. + +### Running tests & snapshots + +Tests use snapshots to ensure that the kits and their recipes work as expected and to prevent regressions. + +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. + +The rendered output is then compared to stored snapshots to ensure that the kit's recipes work as expected. + +To update the snapshots, run the following command from the `src/Toolkit/` directory: +```shell +# Remove existing snapshots (may be useful if some Twig code examples were removed) +rm -fr tests/Functional/__snapshots__ + +# Run tests and update snapshots +php vendor/bin/simple-phpunit -d --update-snapshots + +# Add the updated snapshots to git +git add tests/Functional/__snapshots__ +```