Documentation for the RoundingWell frontend can be found within README.md files throughout this repo.
We use npm for our package manager
You will need Node.js. It is recommended that devs install nvm the node version manager. NVM allows you to change node versions on the fly.
Once NVM is installed, activate the right Node version with:
$ nvm use
Then you will need to run
$ npm i
Releases are automated via an npm script. Make a new temporary local branch consisting of the commits you want to release. Then run
$ npm run release
It will automatically create a release branch on origin named release/YYYYMMDD
If that release branch already exists it will increment the branch name ie: release/YYYYMMDD-1
All dates are in UTC.
To make a release outside of this convention, pass it a branch name.
$ npm run release test-foo
This will create the branch release/test-foo
Release branches should never get merged back into develop.
If a hotfix needs to be made to a release, the fix should ideally first be made to develop and picked into a new release.
The new release, if necessary, can be branched off of a previous release, whatever is easiest to compose a release branch containing only the commits desired.
In some situations some fixes must be applied differently to a release branch than to develop. This is ok! The commits specific to a release do not need to go back into develop.
Essentially this follows the release branches with Gitlab flow
Test releases are built with sourcemaps and follow the same pattern as a regular release.
Besides the build difference, the branch name will be test/YYYYMMDD.
These branches are useful for sharing to ship to dev sandboxes, and should not be used in production.
All development work should branch off of and PR into the develop branch.
There are two npm commands most useful for development:
Useful for local development with vite local dev-server and the backend docker instance
$ npm run dev
To develop in the Cypress gui:
$ npm test
Occasionally the vite server does not release the port, so dev-ing in either environment uses the wrong port and fails. To fix this try:
$ npm stop
If this doesn't work try turning your computer off and then on again 😜
-
Marionette.Toolkit Toolkit adds the
Appclass for an Application tree. EachApphas a lifecycle and an attached state model. Apps are best for requesting data, packaging it and choosing the correct views to show. Toolkit also comes withComponentfor making generic encapsulated components such as datepickers or other widgets. In this program Apps have been made async by default.A typical app will look like:
const MyApp = Toolkit.App.extend({
onBeforeStart(options) {
this.setView(new MyLayoutView());
this.showChildView('header', options.headerText);
this.showView();
},
beforeStart() {
return Radio.request('entities', 'data');
},
onStart(options, data) {
this.showChildView('content', new DataView({ model: data }));
}
});Components should be configurable but not built to be extended. They can also act as a wrapper for 3rd party widgets such as jquery plugins.
A component controls a region and a view combined with a state model, providing a consistent API for interaction.
- Backbone.Store A small but important library that ensures there is only a single instance of a model in memory. It is used for both server models and to sync state models across applications.
const MyModel = Backbone.Model.extend({...});
const MyUniqueModel = Backbone.Store(MyModel);
const myUniqueModel = new MyUniqueModel({ id: '1', foo: 'bar' });
const sameModel = new MyUniqueModel({ id: '1' });
sameModel.get('foo') === 'bar'; // true
const nonUnique = new MyModel({ id: '1' });
nonUnique.get('foo') === 'bar'; // false- Store.js A library for accessing localstorage across browsers
This project uses Font Awesome Pro and should be setup globally to work with npm for devs. Logging into the doc page will provide the license needed.
Icons are loaded with subsetting. To use an icon with Font Awesome it needs to be set in package.json
"fontawesome": {
"far": ["check"],
"fas": ["check"],
"fal": ["acorn"]
},The above example would make available solid and regular check and light acorn. To access the icon, use the following template helper:
Handlebars templates and stylesheets should be imported directly into the modules they're used. Handlebars can also be made inline using the ``hbs```` template literal
import CompiledTemplate from './template-file.hbs';
import 'some-styles.scss';
const OtherTemplate = hbs`
<div class="other-template">
This multi-line template will be precompiled during the build process.
</div>
`;Feature Flags are intended to protect users from new code that isn't fully baked or to allow for gradual rollout. Right now we have one flag for development purposes.
if (_DEVELOP_) {
// new code
}Flags are best used such that a minimal amount of changes are made when the flag is being removed.
// Bad
function foo() {
if (flag) {
doNew();
} else {
doOld();
}
}
// Good
function foo() {
if (!flag) {
doOld();
return;
}
doNew();
}It also may be better to duplicate larger areas of code for fewer easier to remove flags.
// Bad
function foo() {
if (flag) foo();
bar();
baz();
if (!flag) bazinga();
quxx();
}
// Good
function foo() {
if (!flag) {
bar();
baz();
bazinga();
quxx();
return;
}
foo();
bar();
baz();
quxx();
}Outside of linting there are some recommendations for code standards that will help in long term maintenance.
- SASS follows a general BEM format. Ideally do not make deep elements, but start a new block if additional descriptors are needed.
- Favor object composition over class inheritance
- Within reason functions should ideally accomplish one task in less than 10 lines unless logically trivial. If it is getting to big, break up the function.
- Similarly modules should ideally get no larger than 300 lines or so. This is a general guideline and not a rule.
- Use only .js- prefixed selectors if at all possible from the code. Do not use style classes, ids, or tagnames if it can be avoided.
- Utilize the ui hash on views and avoid using the $el if possible. Never use $ directly within a view. Worst case use this.$el or this.$.
- The view should have say over only the DOM inside its own template or in the case of a CollectionView sometimes its direct children. Avoid allowing deep reaching within the DOM or anything external changing the DOM besides the view itself.
- Anything AJAX should happen within the entities service only.
- Generally it is better to store state on a state model than to append a property to an instance.
- Events and handlers should be named
verb:subjectorcontext:verb:subjectbased on what happened not what will happen ie:
triggers: {
'click .js-button1': 'show:modal' // bad
'click .js-button2': 'click:button2' // good
},
childViewTriggers: {
'click:button': 'button:clicked', // bad
'click:button': 'listItem:click:button' //good
},
onShowModal() {
console.log('The naming of this handler suggest a modal was just shown');
},
onClickButton2() {
this.showModal(); // It's ok for a handler to simply call a single action
}Use guards to handle the exception on functions when possible ie:
// Good
doFoo(options) {
if (!options.bar) {
this.doSomethingElse();
return;
}
return 'Foo:' + options.bar;
}
// Bad
doFoo(options) {
if (options.bar) {
return 'Foo:' + options.bar
} else {
this.doSomethingElse()
}
}It is our intention to open source by default. Ideally any generic solution can be extracted, well documented, and tested. Open sourcing encourages better code, collaboration with outside developers, and potentially free battle-testing, bugfixes and features from the public.
Libraries for public consumption are licensed with the MIT License.
Currently our OS projects are available mainly at https://github.com/RoundingWellOS
Each project contains its own documentation for contributions.
Additionally we actively encourage contributing to other projects. Don't know where to start? Look at documentation or tests for any of the libraries we use.