To contribute and run the styleguide, you will need few things :

• 🔀 Git - Version control system

• either:

  • 📗 NodeJS 8+ - JavaScript runtime used to build the project
  • 🐈 Yarn - Dependency manager built on top of the NPM registry

• or:

  • 🐳 Docker - Container platform provider
  • 🐳 docker-compose - Tool for defining and running multi-container Docker applications

Then, to install the project on your environment :

$ git clone git@github.com:epfl-si/elements.git
$ cd ./elements
$ yarn

Docker variant:

$ git clone git@github.com:epfl-si/elements.git
$ cd ./elements
$ docker-compose up builder

As listed in the package.json you have 3 commands available :

• $ yarn start : Will launch a live reloaded server to help you during development
• $ yarn build : Will build your assets for production usage
• $ yarn deploy : Will deploy the styleguide in the dedicated gh-pages

With Docker, you can run:

• $ docker-compose up builder same as $ yarn build but in containers
• $ docker-compose up server same as $ yarn start but in containers

• Error: You don't have any local Toolbox Reader bundles to use... Please connecte yourlsef before retrying
  • Faulty node_modules/toolbox-utils/tasks/prepare.js, Line 17
  • Fix with:
    • mkdir ~/.toolbox && cd ~/.toolbox
    • wget https://cdn.jsdelivr.net/gh/frontend/toolbox-reader@2.2.2/build/static/css/main.css
    • wget https://cdn.jsdelivr.net/gh/frontend/toolbox-reader@2.2.2/build/static/js/main.js

This project follows the git-flow's guidelines. It means you must use the following command to start a new release from your local dev branch :

$ git flow release start x.x.x

Because a new release can impact a lot of projects who use Element, you must precisely list* all the updates made on the components markup in the CHANGELOG.md.

*Check previous versions to give you an idea of how to write it the right way

Then, don't forget to update the version number in the VERSION and the package.json files.

Commit everything !

First, you must complete the git-flow release process with the following command :

$ git flow release finish -p 'x.x.x'

Because the previous command will normally push your release commits and tag, simply go on Github* and copy/paste the release's changelog content in the release's description. (go directly using https://github.com/epfl-si/elements/releases/edit/x.x.x)

Complete every commit and tag message if needed. Then put yourself in your local master branch and type the following command to start the build publishing task :

$ git checkout master
$ sh publish.sh x.x.x

That's it ! If everything went fine, the new release's build is available on the dist/frontend branch thanks to you !

Not all images in the styleguide are needed in the dist/frontend branch. Most of them only serve a presentation purpose and would be a burden for the production builds. For this reason the WHOLE /images/styleguide/ FOLDER is removed during publishing, in the publish.sh script.

If you want to ship images to the production build, just make shure they are in the /images/ folder or any subfolder, as long as it is not named /images/styleguide/.

All the images in the /images/styleguide/ folder will remain available when running yarn start or deploying the styleguide on a gh-page.

• A $ yarn deploy should deploy the styleguide in the dedicated gh-pages

The project is using the Gitflow workflow. It defines a strict branching model designed around the project release.

You can learn more on the following resources :

• Vincent Driessen's post
• Gitflow Workflow guide
• git-flow cheatsheet