Skip to content

Latest commit

 

History

History
108 lines (77 loc) · 4.93 KB

CONTRIBUTING.md

File metadata and controls

108 lines (77 loc) · 4.93 KB
Raw

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

Reporting an issue

If you either 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 as well, 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:

$ git clone [email protected]:<USERNAME>/symfony-ux.git symfony-ux
$ cd symfony-ux
# Add the upstream repository, to keep your fork up-to-date
$ git remote add upstream [email protected]:symfony/ux.git

Setting up the development environment

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

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

$ composer install
$ corepack enable && yarn 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.

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 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/):

  • yarn run build: build (compile) assets from the package,
  • yarn run watch: watch for modifications and rebuild assets from the package,
  • yarn run test: run the tests from the package,
  • yarn run check: run the formatter, linter, and sort imports, and fails if any modifications
  • yarn run check --write: run the formatter, linter, imports sorting, and write modifications

Thanks to Yarn Workspaces, you can also run these commands from the root directory of the project:

  • yarn run build: build (compile) assets from all packages,
  • yarn run test: run the tests from all packages,
  • yarn run check: run the formatter, linter, and sort imports for all packages, and fails if any modifications
  • yarn run check --write: run the formatter, linter, imports sorting for all packages, and write modifications

Useful Git commands

  1. To keep your fork up-to-date with the upstream repository and 2.x branch, you can run the following commands:
$ git checkout 2.x && \
  git fetch upstream && \
  git rebase upstream/2.x && \
  git push origin 2.x
  1. To rebase your branch on top of the 2.x branch, you can run the following commands:
$ git checkout my-feature-branch && \
  git rebase upstream/2.x && \
  git push -u origin my-feature-branch