This is the repository in which we develop each element of the GUI. Each module is tested in isolation and put into an JSON object that keeps track of all versions.
We try to keep our rules simple.
We call each module GUI Ingredient
and a compiled mix GUI Blend
. The GUI Blender
is provided to help you pick your mix.
Ingredient
can be blended together at will.
Ingredient
get a new version when anything changes. We try to keep HTML changes to the absolute minimum. Older versions will always be avaliable but might not be supported anymore.
New versions are submodules pointing to a tag in the repository of the module. Each version must be referenced in the module.json
and the latest version
must be marked in the package.json
. The changelog is maintained in the Readme.md
file in each version.
The semantic versioning in the GUI follows this principle: [HTML changes]
.[JS changes]
.[Less/SVG changes]
as of version 2.0.0
. New modules will start
with version 2.0.0
to clearly communicate that they follow this version principle.
The reason for this is our focus on updatability and maintainability. We want to make it easy for everyone to assess the impact of each change. HTML
changes are most difficult to implement as these changes will typically be done in a database or another larger system. Javascript changes will be easier as
you may only have to replace the gui.min.js
file unless you integrated other js functionality with it. Lastly Less and SVG changes will be the easiest as
this typically means you just have to replace the gui.min.css
file. We hope this makes it easier to integrate with the GUI.
(If we introduce a new feature that comes with a new class(you could argue an HTML change) we still keep to the smallest change: 2.0.[change]
.)
To run this repo first download, install all dependencies in the root and initialize all submodules.
To see an overview of all Ingredient
you can run grunt
in the root or visit the GH-Pages hosted by GitHub.
To work on a module and watch its files you can run grunt
in each repository. Please note that you cannot make changes to any module in this repo.
Each
Ingredient
version has atests
folder that contains various html files to be tested.
You can see the tests here. Note that those tests are for stress testing only. Find documentation for the GUI on the GEL pages.
To include a new module, create a new repo and prefix it with
GUI-
orGUI_
for core modules.
To add this new module into the source you have to create a new folder with the same name and include each version (tagged) in a version folder. All versions
have to be noted in the module.json
. See the boilerplate for a new module in the here: ._template/module
.
See more in Workflow.
See below the workflow for adding a new module.
GUI-
or GUI_
for core modules._template/module
folder[-Module-]
with module name in README.md
, module.json
, package.json
, less/module-mixin.less
, js/module.js
core
is up to datemodule.json
to reflect use of js
, less
, svg
etc.master
See below the workflow for changes to a module.
package.json
version bumpmodule.json
version bumpREADME.md
version bumpREADME.md
whatsnewWestpacCXTeam/GUI-source#[issue number]
or reference commits with: WestpacCXTeam/[repo name]@[commit hash]
and fix issues with: fixed WestpacCXTeam/GUI-source#[issue number]
(nb. fixed
keyword will automatically close the issue once merged to master
)master
(master
powers GitHub pages)Run GUI-source and GUI-docs and upload to ubuntu server, install blender script and make sure we have 404 pages in place for transition
git submodule add git@github.com:WestpacCXTeam/GUI-[module].git [module]/[version]
grunt
to compile index.html
, GUI.json
and all READMEsgrunt all
to compile _sandbox
filesmaster
(master
powers GitHub pages)GUI-source-master
and update to latest master releasegrunt new-example
to automatically add the missing _includes/modules
and _examples
folders_includes/modules/[module]/[version].liquid
file and updated its documentation_examples
and add whatsnewgrunt
to compile (current devBrand) and run server (or) grunt server
if you don't need to compilenode remote/server-dev.js
from /blender
(while GUI-docs server is running)grunt prod-all
to build the production filesmaster
GUI-docs/jekyll/_site
in docs.zip
GUI-source-master
folder found in GUI-docs/GUI-source-master
in gui.zip
gui.zip
and docs.zip
to /www/GUI/.temp
folder (check no version folders are empty)
(or use scp /Users/username/Desktop/gui.zip deploy@128.199.200.220:/www/GUI/.temp/gui.zip
from your local computer)server.js
, .template/
, assets/
possibly package.json
and .guiconfig
) [For Blender updates only]npm i
in blender/remote
folder [For Blender updates only]/www/GUI/.temp
folder and run: unzip gui.zip -d ../safety-net
/www/GUI
folder and run: rm -rf GUI-source-master
GUI-source-master
from folder safety-net
to the /www/GUI
folderforever list
[For Blender updates only]forever restart 0
or forever start -l blender.log --append -o blenderOut.log -e blenderError.log server.js
[For Blender updates only]forever list
and blend something to test [For Blender updates only]/www
folder and rename construction2.html
to construction.html
to redirect traffic to this file with nginx/www/GUI
folder and run: rm -rf BOM
| rm -rf BSA
| rm -rf STG
| rm -rf WBC
| rm -rf WBG
| rm -rf BT
/www/GUI/.temp
folder and run: unzip docs.zip -d ../
/www
folder and rename construction.html
to construction2.html
to direct traffic back to the sitesudo reboot
if necessaryThe following are a few things to remember:
The module.json
file that is then compiled into the GUI.json file is the engine of the GUI modular system.
{
"ID": "moduleID", #the unique ID of the module
"name": "Module name", #the name of the module
"description": "some text", #description used in the blender
"category": "cateogry", #category for blender and doc pages
"versions": {
"1.0.0": { #listing of all versions
"dependencies": [], #dependencies on any other modules?
"js": true, #does this module include javascript
"less": true, #does this module include less
"svg": false, #does this module include svgs
"font": false, #does this module include web fonts
"size": 12 #what's the estimated file size
},
"1.0.1": {
"dependencies": [],
"js": true,
"less": true,
"svg": true,
"font": false,
"size": 13
},
"1.0.2": {
"dependencies": [],
"js": true,
"less": true,
"svg": true,
"font": true,
"size": 27
}
},
"hash": "f718a7d02eab6d114b8375aca7c23d98" #checksum of this module
}
We are trying to make as little changes to the overall build as possible.
submoduleSync
task to ensure submodule updates are sync’d between developers/docs
directory_sandbox
icon output pre build and update ._template
files.guiconfig
fileCopyright (c) 2019 Westpac. Licensed under the GNU GPLv2.