unibz Pattern Library

Installation & Commands

This repository contains the source files of the web assets (CSS, JavaScript, etc.) used for unibz web projects, as well as the documentation and source files for the pattern library that showcases the usage of the web assets using a tool called fractal.

The build process uses gulp to handle asset compilation, minification and other tasks.

It is recommended that gulp and fractal are installed globally on you machine.

NOTE: In the documentation yarn is used to handle dependencies, if you do not have yarn installed (recommended) you can replace yarn commands with npm.

Repository structure

There are two relevant repositories, the “source” and the “versions” repository.

The source repository holds all source files to build the library and it’s tags represent the available versions of the web assets.

The versions repository contains all compiled versions of the library and is the code that is intended for public usage and distribution.

The versioning of both repositories is handled via the build system. Read below for more information.

Code

  • Source files for the web assets is located in the src folder.
  • Source files for the pattern library are located in the src-fractal folder.

Installation

  1. Clone this repo on your machine.
  2. Inside the cloned folder run yarn setup (or npm run setup). This will install the dependencies and clone the repository containing the previous versions of the pattern library into a folder called versions.

When the setup is done the folder structure should look like this:

.git/             # "source" repository
gulpfile.js/      # build system code and configuration
node_modules/     # dependencies
src/              # web assets source code
src-fractal/      # pattern library source code
versions/
  .git/           # versions repository
  .../            # folders with version names
...               # other files

Development

To run the project and watch for changes run:

yarn watch

Then go to http://localhost:3000/ in your browser to see the pattern library generated by fractal.

To create a production build run:

yarn prod

This will create a folder named .build that contains a static export of the fractal pattern library as well as the web assets.

This build is intended to check the production build without creating a definitive version. The .build is ignored via .gitignore.

Versioning & Creating a release

The library uses semver. The version number is handled in the package.json version key.

After making changes that require a new version number:

  • Update the changelog.md file to reflect the changes
  • Update the version number in package.json

After that run the following command:

yarn release

The command will fail if:

  • No versions folder exists
  • The version you are trying to create already exists

If the command is successful it will:

  • Compile all the assets
  • Create a static build of the fractal pattern library
  • Create a commit in the source repository: “Version XXX” (if you did not commit before, otherwise it will tag the last commit)
  • Create a tag
  • Push to master
  • Create a commit in the versions repository: “Version XXX”
  • Push to master
  • Create a index.html file, that serves as versions overview

File location

  • The source files for the web assets are located in the src folder.
  • The source files for the pattern-library are located in the src-fractal folder.
  • The build system tasks are located inside the gulpfile.js folder.
  • The main configuration for the build system is located at gulpfile.js/config.js