Standards
Last updated
Was this helpful?
Last updated
Was this helpful?
Note: These standards are by no means set in stone, and as a community, we always want to be iterating and improving Mojaloop. If you want to propose a change to these standards, or suggest further improvements, please reach out to the Design Authority Channel on the Mojaloop Slack (#design-authority)
Mojaloop has some that are important to understand and adhere to when contributing to the codebase.
These invariants are derived from and other business requirements as decided upon by the Mojaloop Technical Governance Board, API Change Control Board, Design Authority and Product Council. They are intended to ensure the platform retains certain characteristics important for national infrastructure grade operation.
Please ensure you are familiar with the invariants before contributing to the codebase.
The following runtime standards apply to Mojaloop.
Javascript
NodeJS is the standard Runtime for all Mojaloop services and components for the execution of Javascript source-code files.
Our goal is to ensure that all NodeJS based services run against the latest Active LTS
(Long Time Support) version of NodeJS following the official .
Container (Docker) Operating System (OS)
Mojaloop's Micro-services are built on top of the node:<NODE_ACTIVE_LTS_VERSION>-alpine
base image, where NODE_ACTIVE_LTS_VERSION
is the current NodeJS LTS following the official . Refer to for a full list of official NodeJS Alpine Docker images.
NOTE: When specifying the
NODE_ACTIVE_LTS_VERSION
, use the full semantic version such as<MAJOR>-<MINOR>-<PATCH>
.
node:16.15.0-alpine
<-- This is OK
lts-alpine3.16
<-- This is NOT OK
Standard Javascript Dockerfile
example:
Standard Typescript Dockerfile
example:
The Mojaloop Community provides a set of guidelines for the style of code we write. These standards help ensure that the Mojaloop codebase remains high quality, maintainable and consistent.
The goal of these guides is to ensure an easy developer workflow and reduce code commits that contain changes for the sake of style over content. By reducing the noise in diffs we make the job of reviewers easier.
To avoid confusion and guarantee cross-language interpolation, follow these rules regarding naming conventions:
Do not use abbreviations or contractions as parts of identifier names. For example, use SettlementWindow
instead of SetWin
.
Do not use acronyms that are not generally accepted in the computing field.
Where appropriate, use well-known acronyms to replace lengthy phrase names. For example, use UI
for User Interface
.
Use Pascal case or camel case for names more than two characters long depending on context (e.g. class names vs variable names). For example, use SettlementWindow
(Class) or settlementWindow
(Variable).
You should capitalize abbreviations that consist of only two characters, such as ID
instead of Id
when isolated. For example, use /transfer/{{ID}}
instead of /transfer/{{Id}}
when representing ID
as a URI parameter.
Avoid abbreviations in identifiers or parameter names. If you must use abbreviations, use camel case for abbreviations that consist of more than two characters, even if this contradicts the standard abbreviation of the word.
Use screaming (capitalized) Snake case for Enumerations. For example, use RECORD_FUNDS_OUT_PREPARE_RESERVE
.
Use 2 spaces for indentation
Use single quotes for strings except to avoid escaping.
No semicolons. (see: 1, 2, 3)
Note: Standard and Typescript
As we start to introduce more Typescript into the codebase, Standard becomes less useful, and can even be detrimental to our development workflow if we try to run standard across the Javascript compiled from Typescript. We need to evaluate other options for Standard in Typescript, such as a combination of Prettier + ESLint.
While YAML deserializers can vary from one to another, we follow the following rules when writing YAML:
2 space indents
Always indent child elements
Do not align values
The Shebang should respect the user's local environment:
This ensures that the script will match the bash
that is defined in the user's environment, instead of hardcoding to a specific bash at /usr/bin/bash
.
When referring to other files, don't use relative paths:
This is because your script will likely break if somebody runs it from a different directory from where the script is located
Documentation should be written in Markdown format.
Sequence diagrams should use PlantUML
All discussion documents should be placed in /community/archive/discussion-docs.
The use of Google Docs and other private tools is not advised for community wide collaboration
Along with guidelines for coding styles, the Mojaloop Community recommends the following directory structure. This ensures that developers can easily switch from one project to another, and also ensures that our tools and configs (such as .circleci/config.yml
and Dockerfile
s) can be ported easily from one project to another with minor changes.
The directory structure guide requires:
The following Config files help to enforce the code styles outlined above:
.editorconfig
.nycrc.yml
.tsconfig.json
.eslintrc.js
It is important to ensure that the latest Dependencies are used to mitigate security issues.
And add the following scripts to package.json
:
Run the following script to check for any dependencies that need upgrading:
If required, one can execute the following command to install the latest dependencies:
If a dependency cannot be upgraded for a valid reason, then .ncurc.yaml
file should added to the project root with said dependency added to the reject
list with an appropriate comment
as follows:
The following approaches are utilized to enforce that dependencies are kept up-to-date:
Git Pre-Commit Hook
This will ensure that a validation check will occur on a Developer's local machine when making any Git Commits.
Note: It is possible to circumvent this by using
-n
parameter when committing usinggit commit -nm <message>
. A CI (Continuous Integration)test-dependencies
Validation Check (see next section) is thus required to ensure enforcement.
Automated CI Validations
This will ensure that a validation check occur during reviews and releases, and also ensure that Git Pre-Commit Hook are not circumvented.
CI Configs (i.e. .circleci/config.yml
) must contain a test-dependencies
Validation Check CI Job (i.e. npm run dep:check
) for all Pull-Request, merges to Main branch, and Tagged Releases.
And add the following scripts to package.json
:
Run the following script to check for any dependencies that need upgrading:
NOTES
Ensure to commit any fixes applied by the above command to the
package-lock.json
.Ensure that all tests pass after applying any fixes as they may result in a dependency version change which could introduce breaking changes.
If there is no fix, then audit-ci.jsonc
file should added to the project root with said vulnerability advisories ID
added to the allowlist
with an appropriate comment
as follows:
Git Pre-Commit Hook
This will ensure that a vulnerability checks will occur on a Developer's local machine when making any Git Commits.
Note: It is possible to circumvent this by using
-n
parameter when committing usinggit commit -nm <message>
. A CI (Continuous Integration)vulnerability-check
vulnerability Check (see next section) is thus required to ensure enforcement.
Automated CI Validations
This will ensure that auditing checks occur during reviews and releases, and also ensure that Git Pre-Commit Hook are not circumvented.
CI Configs (i.e. .circleci/config.yml
) must contain a vulnerability-check
vulnerability Check CI Job (i.e. npm run dep:check
) for all Pull-Request, merges to Main branch, and Tagged Releases.
These guidelines are meant as recommendations for writing code in the Mojaloop community (or code that will be adopted into the community). If you are writing code that you wish to donate code to the community, we ask that you follow these guidelines as much as possible to aid with the consistency and maintainability of the codebase. Donations that adhere to these guidelines will be adopted more easily and swiftly.
In the Mojaloop OSS Community, we are prefer the following tools and frameworks:
Package Management: npm
By using these tools and frameworks, we maintain a high level of consistency and maintainability across the codebase, which keeps our developers productive and happy. While we don't mandate that donated codebases use these same tools and frameworks, we would like to stress that adoptions that use different tools could create an undue maintenance burden on the Community.
This section provides guidelines regarding the adoption of a contribution to the Mojaloop Open Source repositories. Adoption is the process where we as the community work with a contributor to bring a contribution into alignment with our standards and guidelines to be a part of the Mojaloop OSS Codebase.
Note: Code Contributions are evaluated on a case-by-case basis. Contributions that don't align to these guidelines will need to go through the incubation phase as described below. Other misalignments to these standards (for example, framework choices) may be added to a roadmap for further improvement and OSS Standardization in the future.
Before a contribution is to be considered for adoption, it:
Should adhere to the above Style and Design + Implementation Guides.
Should contain documentation to get started: the more, the better.
Create a private repo within the Mojaloop GitHub organization for the adopted code.
Have a sub-team of the DA take a look to make sure its portable (to OSS) - aligns with L1P principles, etc, and ensure design is in line with standards.
Check Licensing of the contribution and any new dependencies it requires, and add the standard Mojaloop License with attribution to donor/contributors.
Assess the current state of the codebase, including documentation, tests, code quality, and address any shortfalls.
Assess Performance impact.
Create action items (stories) to update naming, remove/sanitize any items that are not generic
Inspect and discuss any framework and tooling choices.
If a decision is made to make any changes, add them to the roadmap.
Make the project public on Mojaloop GitHub.
Enable CI/CD Pipelines and publish any relevant artifacts, such as Docker Images or npm modules.
Review and recommend a module or course for the Mojaloop Training Program if needed and relevant for this contribution.
1. What if I want to contribute code, but it doesn't align with the code style and framework/tool recommendations in this guide?
Contributions are accepted on a case by case basis. If your contribution is not yet ready to be fully adopted, we can go through the incubation phase described above, where the code is refactored with our help and brought into alignment with the code and documentation requirements.
2. These standards are outdated, and a newer, cooler tool (or framework, method or language) has come along that will solve problem x for us. How can I update the standards?
Writing high quality, functional code is a moving target, and we always want to be on the lookout for new tools that will improve the Mojaloop OSS codebase. So please talk to us in the design authority slack channel (#design-authority
) if you have a recommendation.
Mojaloop's CI Jobs are executed against the current Ubuntu LTS version following the official .
Mojaloop's Helm Charts ( ) are deployed and verified against the current Kubernetes LTS version following the official .
These style guides are chosen because they can be easily enforced and checked using popular tools with minimal customization. While we recognise that developers will have personal preferences that may conflict with these guidelines we favour consistency over these rules.
Ref:
Mojaloop uses the Javascript code style dictated by . For a full set of rules, refer to the , but as a brief set of highlights:
Refer to the for the standard typescript configuration.
Credit: these examples were taken from the
For other recommended bash conventions, refer to this blog post:
Hand drawn diagrams should use an editable SVG format (example - architecture / component / block / state transition diagrams) exported from
NOTE: Please ensure that you have imbedded the editable diagram when exporting the SVG from !
EditorConfig is supported out of the box in many IDEs and Text editors. For more information, refer to the .
For a more detailed list of the recommended typescript configuration, including package.json
, jest.config.js
and more, refer to the .
NodeJS projects should install using the following command:
The dep:check
should be added as a git commit pre-hook using as follows:
NodeJS projects should install using the following command:
If required, one can execute to apply any known available fixes:
The audit:check
should be added as a git commit pre-hook using as follows:
For more information, refer to the FAQ .
Web Server:
Web UI Framework:
Runtime Configuration: , with for legacy. (both for env variables and config files)
Logging: library, built on top of Winston
Containers and Orchestration: and
Unit Testing: For existing tests, , but we are currently moving over to for new codebases.
Test Coverage:
CI:
Should be in-line with the .
Contain tests with a high level of coverage. At a minimum, a contribution should contain unit tests, but a test suite with unit, integration and functional tests is preferred. Refer to the for more information.
Announce on the slack channel.
Review the information on for Mojaloop.
Process for creating new in Mojaloop.
It's a good idea to ask about major changes on . Submit pull requests which include both the change and the reason for the change. Feel free to use GitHub's "Draft Pull Request" feature to open up your changes for comments and review from the community.
Pull requests will be denied if they violate the .
We use the
See policy.