From 558a1edc337cc6fe19e56e543dec83e97a219977 Mon Sep 17 00:00:00 2001 From: Sonata CI Date: Sun, 8 May 2022 09:17:13 +0100 Subject: [PATCH] DevKit updates (#331) --- .github/workflows/frontend.yaml | 4 +-- CONTRIBUTING.md | 64 +++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 2 deletions(-) diff --git a/.github/workflows/frontend.yaml b/.github/workflows/frontend.yaml index e70b068b..80abd162 100644 --- a/.github/workflows/frontend.yaml +++ b/.github/workflows/frontend.yaml @@ -9,8 +9,8 @@ on: - cron: '30 0 * * *' push: branches: - - 4.x - - 5.x + - 1.x + - 2.x pull_request: jobs: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 53c82d80..88e04dbb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,6 +22,7 @@ interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). * [Coding style](#coding-style) * [Documentation](#documentation) * [Tests](#tests) + * [Frontend](#frontend) * [Writing a pull request](#writing-a-pull-request) * [Subject](#subject) * [Changelog](#changelog) @@ -166,6 +167,69 @@ Some rules have to be respected about the test: * Most of the time, the test class SHOULD have the same name as the targeted class, suffixed by `Test`. * The `@expectedException*` annotations are prohibited. Use `PHPUnit_Framework_TestCase::setExpectedException()`. +#### Frontend + +Frontend assets are all located under `assets` directory, with the following structure: + +* `assets/js` for the JavaScript files +* `assets/scss` for the [SCSS](https://sass-lang.com/) files +* `assets/images` for the images +* `assets/vendor` for the third party assets that can't be loaded via [NPM](https://www.npmjs.com/) + +This `assets` directory contains only the source code, and it is not directly accesible for the +website, because is not placed under the `src/Resources/public`. + +If you take a look at the `src/Resources/public` you will see a lot of minified assets, this is done with +[Webpack](https://webpack.js.org/), we are using [Webpack Encore](https://github.com/symfony/webpack-encore) to configure and run it. + +Similar to what Composer is for PHP there is a package manager for the frontend stack, called NPM and we declare our +dependencies on `package.json` and the lockfile is `package-lock.json`, because we are using [NPM](https://www.npmjs.com/). +It is common to commit the lockfile in the case of frontend, because dependencies tend to upgrade really often and it +affects directly the compiled files. + +If you PR is focused on fixing or improving the frontend you might need to modify +JavaScript or CSS code. To do so, you will first need to install the dependencies: + +```bash +npm clean-install + +# if you want to upgrade some package you SHOULD run instead +npm install +``` + +To compile assets before the pull request you should run: + +```bash +npx encore production +``` + +This command will make the lint checks and compile for production usage the assets. You can also run +lint checks ([ESLint](https://eslint.org/) and [Stylelint](https://stylelint.io/)) with: + +```bash +npx eslint assets/js +npx stylelint assets/scss +``` + +We have some strict rules following the most popular coding standards for JavaScript and SCSS. + +* [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript) +* [Stylelint Recommended Configuration](https://github.com/stylelint/stylelint-config-recommended) + +We also use [Prettier](https://prettier.io/) to do the code formatting for all the `assets` folder, to run it manually: + +```bash +npx prettier --write assets +``` + +You can also configure your IDE to do it automatically on save: + +* [PHPStorm](https://www.jetbrains.com/help/phpstorm/prettier.html) +* [VSCode](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) + +In case you need more documentation before making your Pull Request, please consider reading +the documentation of all mentioned tools. + ### Writing a Pull Request #### Subject