Ambassador Conventions

A UX and design pattern library for all Ambassador apps.

Inspired by Mailchimp's Pattern Library.

A living version of the Ambassador style guide.

Convention

An agreement between two or more states, often more, concerning matters of common interest. While supposedly used for lesser matters than embraced in a treaty, it often deals with important subjects indeed – international postal and copyright laws, for example, of the law of the sea.

Source

Getting the conventions site running

Make sure you cd to your favorite directory. Then we'll clone the conventions repo:

$ git clone [email protected]:GetAmbassador/ambassador-conventions.git

Move into the project:

$ cd ambassador-conventions

Install Git hooks:

$ ln -s ../../git-hooks/prepare-commit-msg .git/hooks/prepare-commit-msg
$ ln -s ../../git-hooks/pre-push .git/hooks/pre-push

The pre-push hook requires re-initialization of the repo:

$ git init

Make sure the pre-push hook is executable:

$ chmod +x .git/hooks/pre-push

If Node is not installed on your machine it will need to be installed. Install instructions are here

Install nvm using the following command:

$ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.30.1/install.sh | bash

Quit the terminal and reopen it so you have access to nvm.

To make sure you have Node version 10.11.0 installed enter the following commands:

$ nvm install 10.11.0
$ nvm alias default 10.11.0

You can verify that the correct version of Node was installed using the following command:

$ node -v

To make sure you have npm version 6.4.1 installed enter the following command:

$ [sudo] npm install [email protected] -g

You can verify that the correct version of npm was installed using the following command:

$ npm -v

Rebuild node-sass using the following command:

$ npm rebuild node-sass

Install Node packages:

$ npm install

If Bower is not installed on your machine it will need to be installed:

$ npm install -g bower

Install Bower packages:

$ bower install

You dev area should now be all set! You should now be able to start a local webserver and view the site using:

$ grunt serve

Once grunt serve has started you should be able to access the site at http://localhost:9000/

If grunt fails on Error: Cannot find module 'liftoff', I found a workaround to be using nvm to install node v14.16.1, then install grunt-cli globally and grunt locally:

$ nvm install 14.16.1
$ npm install -g grunt-cli
$ npm install grunt

Then you can switch back to version 10.11.0, and retry starting the server with:

$ nvm use default
$ grunt serve

If you have a port conflict with 9000 you may need to adjust the port used in the Gruntfile to an unused port or disable/stop the application using port 9000 on your machine.

Local Testing

To run tests locally, run grunt test:local

Releasing

When you are ready to release a new version of Ambassador Conventions please follow this procedure.

1. Update the version in bower.json.
2. grunt build
3. Create a new issue in conventions-bower for the new version.
4. Copy dist/ga-conventions.min.js, dist/ga-conventions.templates.min.js, dist/ga-conventions.css, dist/ambassador/styles/ and dist/components over to your new branch for conventions-bower
5. Update the version in bower.json on conventions-bower.
6. If any bower components have been added be sure to include them in the conventions-bower bower.json.
7. If any dependencies have been updated, be sure to update them in conventions-bower bower.json
8. Push and merge on conventions-bower.
9. Create a tag on conventions-bower for the new version. git tag -a v0.1.0 -m 'Releasing v0.1.0'
10. Create a tag on ambassador-conventions for the new version. git tag -a v0.1.0 -m 'Releasing v0.1.0'
11. Create a new release in conventions-bower following the naming convention of previous releases Ambassador Conventions - vX.X.X