To contribute and run the styleguide, you will need few things :
- 🔀 Git - Version control system
- 📗 NodeJS 18 - JavaScript runtime used to build the project
- 🐈 Yarn - Dependency manager built on top of the NPM registry
Then, to install the project onto your workstation:
$ git clone [email protected]:epfl-si/elements.git
$ cd ./elements
$ yarn
As listed in the package.json
, the following commands are available:
$ yarn start
: Will launch a live reloaded server to help you during development$ yarn dist
: Will build your assets for production usage into thedist/
directory
EPFL-Elements uses backstop.js to perform visual regression testing.
💡 Instead of running the steps below on your workstation, you may want to have GitHub actions do the same for you in the cloud. See the next paragraph.
To run a side-by-side comparison between the original state of Elements and your changes using Backstop, you need to have a locally-running Elements Web app as per the previous §. Then:
- Make sure all your changes are committed to git (not necessarily pushed)
- Run
yarn test:prepare
💡 Do not stop the EPFL-Elements Web app to type in this command! Use a new terminal window instead. - Check out the upstream branch for your work (typically
origin/dev
):git checkout origin/dev
- Run
yarn test:reference
- Check out your working branch again, e.g.
git checkout feature/myfeature
- Run
yarn test:changes
- The report should open in your browser automatically. If not, just open the
tests/backstop/html_report/index.html
file in your browser
Whenever one creates or updates (pushes to the underlying branch of) a GitHub pull request, a set of GitHub actions kicks off to perform the same visual regression testing as described in the previous paragraph, except that the processing happens in the cloud.
- Push your work to a feature branch
- If not already done, create a GitHub pull request out of that feature branch
- Wait a few minutes for the GitHub actions to terminate.
💡 If you are feeling impatient and/or bored, browse the repository's Actions tab and click your way through the yellow spinning icons to look at the logs while the GitHub actions are in progress. - If all goes well, the GitHub actions' bots should append two new comments to the pull request's review thread. The second one contains a link to the Backstop report, which is a rather large (~150 Mb) file. In order to take a look at the report:
- Download it by clicking the link
- Unzip the file (💡 Depending on your browser's configuration, this may happen automatically)
- Open the file
backstop-report/html_report/index.html
within the unzipped directory with your browser - If you want to perform additional changes (e.g. to repair regressions spotted by Backstop), just push (or force-push) to the feature branch. When done, the GitHub actions will update the same two review messages in the PR thread (instead of creating new ones).
- Ensure that your
~/.yarnrc
contains a line likeregistry "https://registry.npmjs.org/"
yarn releaseand follow the interactive instructions.
The last step will cause the following things to happen:
- Ensure that you are on the
dev
branch (or bail out if not) - Bump version number
- Commit, tag and push
... And in turn, that last step will cause the following things to happen server-side, using GitHub Actions:
- Create a release on GitHub in .zip format
- Update the online demo on GitHub pages
- Update the
dist/frontend
branch