Elements

EPFL Web Styleguide

👉 View online

Install

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 [email protected]:epfl-idevelop/elements.git
$ cd ./elements
$ yarn

Docker variant:

$ git clone [email protected]:epfl-idevelop/elements.git
$ cd ./elements
$ docker-compose up builder

Run locally

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

Create a new release

1. Git release

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

2. Changelog & versions

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 !

3. Complete the release

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-idevelop/elements/releases/edit/x.x.x)

4. Publish the builds

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 :

$ 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 !

4.1 Note on build images

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.

5. Update github.io

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

Contribute

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