Contribution
The Design Language is an open source project meant to continuously evolve through input and collaboration between our digital teams and our agency partners, and as such it can be contributed to via GitHub. Please refer to the instructions below to get set up and start contributing.
Prepare your environment
Global tools – Ensure you have these minimum requirements installed:
- A command line tool package manager (mac: homebrew / windows: scoop)
- Git command line tools or a GUI for git (We recommend Sourcetree)
- NVM with a node 8+
- NPM version 3+
Clone both of the repositories into folders wherever you’d like to work.
Using your favourite command line / terminal application navigate to each of the newly created folder and run npm install.
Windows only: Once the packages have finished downloading run npm install gulp-cli -g to install Gulp globally on your machine (this only needs to be run once not for both projects).
After the installation has completed you should see a node_modules folder, if you don’t or the installation fails with an error please contact [email protected].
In either of the cloned repos you can now simply run gulp to see a list of possible tasks that can be executed with a description of their output. For more information about the tasks keep reading.
Design Language Assets
Windows only: You will need to navigate to ./src/svgs/ in the commandline and run: git clone --depth=1 [email protected]:emcrisostomo/flags flags
-
gulp tasklist– Lists all the tasks available. -
gulp build– Runs through all the tasks necessary to compile the assets ready for development. -
gulp develop– Watches for any code changes then recompiles the css and javascript as needed. Also, launches a local endpoint (http://localhost:3500) for supplying the assets for development in the portal.' -
gulp tasklist– Lists all the tasks available. -
gulp release– Similar to the build script but uses the currently applied git tag to mark various assets with the correct version.
Design Language Portal
-
gulp develop-portal-cdn– Starts the portal and uses the assets supplied by the production CDN. -
gulp develop-portal-local– Starts the portal and uses the assets supplied by the local endpoint provided by the Assets repo. -
gulp develop-element-local --{component-name}– Generates a special page with just those components loaded using the local endpoint for the assets, e.ggulp develop-element-local --buttons -
gulp develop-element-cdn --{component-name}– Generates a special page with just those components loaded using the production CDN for the assets, e.ggulp develop-element-local --buttons -
gulp release– Runs through the built steps, moves any assets to where they need to be and finishes. applied git tag to mark various assets with the correct version.
Coding standards
Both repositories contain code linting configurations in the root of the repository, .stylelint and .eslint. These ensure that all JS and CSS/SCSS follow the same standard formatting and help to prevent bugs and errors. We recommend that you set up integrated linting in your preferred text editor/IDE. We have provided a list of guides for common editors below:
ESLint & StyleLint
Both of these rule sets are used by the task manager to check code that's being compiled but you can also add them to your IDE so onscreen highlighting.
The following IDEs have full support for inline linting:
Documenting Code
Javascript and SCSS should be documented using JSDoc and SassDoc comments respectively. Please refer to the full documentation of each for proper annotation usage.
Git workflow
Both repositories follow the GitFlow branching model. There are two main branches, master and develop. New features should be added by creating a feature branch from develop. Once you have completed the new feature you can submit a pull request so that the code can be reviewed and merged accordingly. More detailed information can be found here.