Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
211 lines (148 loc) · 9.03 KB

CONTRIBUTING.md

File metadata and controls

211 lines (148 loc) · 9.03 KB

Contributing

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 first

Reporting an issue

If you find a bug, have a feature request, or need help/have a question, please open an issue.

Please provide as much information as possible, and remember to follow our Code of Conduct to ensure a friendly environment for all contributors.

Contributing to the code and documentation

Thanks for your interest in contributing to Symfony UX! Here are some guidelines to help you get started.

Forking the repository

To contribute to Symfony UX, you need to fork the symfony/ux repository on GitHub. This will give you a copy of the code under your GitHub user account. Read the documentation "How to fork a repository".

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

# With GitHub CLI https://cli.github.com/
$ gh repo clone <USERNAME>/symfony-ux symfony-ux

# Using SSH
$ git clone git@github.com:<USERNAME>/symfony-ux.git symfony-ux
$ cd symfony-ux
# Add the upstream repository, to keep your fork up-to-date
$ git remote add upstream git@github.com:symfony/ux.git

Setting up the development environment

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

  • PHP 8.1 or higher - Required for running Symfony components
  • Composer - PHP dependency manager
  • Node.js 22.18 or higher - Required for asset compilation
  • Corepack - Package manager manager (comes with Node.js 16+)
  • PNPM 10.16.1 or higher - JavaScript package manager (installed via Corepack)

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

# Install root PHP dependencies
$ composer install

# Enable PNPM through Corepack, and install JavaScript dependencies
$ corepack enable && pnpm install

Linking Symfony UX packages to your project

If you want to test your code in an existing project that uses Symfony UX packages, you can use the link utility provided in this Git repository (that you have to clone).

This tool scans the vendor/ directory of your project, finds Symfony UX packages it uses, and replaces them by symbolic links to the ones in the Git repository.

$ php link /path/to/your/project

Working with PHP code

Symfony UX follows Symfony PHP coding standards and the Backward Compatibility Promise.

When contributing, please make sure to follow these standards and to write tests for your code, runnable with php vendor/bin/simple-phpunit.

Generate snapshots for UX Toolkit

If you make changes to a component template or add a new one, create or update the EXAMPLES.md of the component. Then, you can (re)generate new snapshots by running:

php vendor/bin/simple-phpunit -d --update-snapshots

Important

Snapshots will not reflect changes if you forget to update the EXAMPLES.md.

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, all compiled through 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 and Symfony Webpack Encore

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

Thanks to PNPM 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 fmt:check: run the code formatter for all packages, and fail if any modifications are needed
  • pnpm run fmt: run the code formatter for all packages, and write modifications
  • pnpm run lint: run the linter for all packages
  • pnpm run lint:fix: run the linter for all packages, and fix any fixable issues

Important

Always run pnpm run build before committing your changes to ensure assets are properly compiled.

Working with Unit tests

We use Vitest for unit testing of the assets, 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:

  • At the project's root, you can run the following commands:
    • pnpm run test:unit: runs the unit tests for all UX packages
  • Inside the assets/ directory of each UX package, you can run the following commands:
    • pnpm run test:unit: runs the unit tests for the package

Important

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 we don't recommend using watch mode.

Working with End-to-End (E2E) tests

Note

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 uses Playwright for browser automation and testing, and a dedicated Symfony application located in the apps/e2e/ directory, which contains many examples of Symfony UX package usages.

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 you have followed the steps in the Setting up the development environment section
  2. Read and follow the instructions in the 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
  • 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: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 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:

$ pnpm run test:browser:ui

Working on documentation

Symfony UX documentation is written in ReStructuredText (.rst) and is located in the docs/ directory of each package.

When contributing to the documentation, please make sure to follow the Symfony documentation guidelines.

To verify your changes locally, you can use the oskarstark/doctor-rst Docker image. Run the following command from the root directory of the project:

docker run --rm -it -e DOCS_DIR='/docs' -v ${PWD}:/docs  oskarstark/doctor-rst -vvv

Useful commands

To keep your fork up-to-date with the upstream repository and 2.x branch:

$ git checkout 2.x && \
  git fetch upstream && \
  git reset --hard upstream/2.x && \
  git push origin 2.x

To rebase your branch on top of the 2.x branch:

$ git checkout my-feature-branch && \
  git rebase upstream/2.x && \
  git push -u origin my-feature-branch