How to write code in Aura Bot global repositories

Introduction

The aim of this document is to establish common minimum rules to contribute in Aura Global repositories: code linting, used libraries and guidelines for working over main and master branches

Programming Languages

aura-bot code is written in typescript 4.3.4 that is a programming language developed by Microsoft on top of Nodejs. Currently we use node engine version 14 and npm version 6.

This means that we follow typescript rules of naming, but we have also added some extra ones, to unify our developments:

• local variables: always in camelCase.
• files: always in lower case letters, dash-separated.
• classes: in PascalCase.
• interfaces: in PascalCase, they do not start with I.
• enums: named in PascalCase, each item also in PascalCase.
• library or server names: always in lower case letters, dash-separated.
• environment variables: in capital letters, underscore-separated.
• functions: always in camelCase.
• asynchronous programming: use await/async pattern when possible, avoid chains of promises.
• adding a feature to an existing server: check the already existing instances of Singleton components and use them directly. Do not create a new instance, this will lead to an error during the start-up or in runtime.
• All servers count on a ConfigurationManager where all its environment variables can be obtained.

Try to use the best programming pattern for each feature, applying always Single Responsibility Point defining small modules, functions or classes that do only one specific task. Find more references for programming patterns:

• Design patterns
• Typescript design patterns

Libraries used

• To write logs, always aura-logging. This logger needs a module name during its initialization: it must be in lower case letters, dash-separated.
  • Review aura-utilities repository to find out more libraries.
• Web servers: expressjs.
• Dependency injection: architect.
• Environment variables configuration validation: joi.
• Database: mongodb, currently version 4.2 but moving in next releases to version 6.
• UnitTest: we use mocha for already existing modules, but we are moving to jest, so all brand-new modules must use jest.
• Mocks-Server: we have developed a mocks server (aura-mocks-server), that mimics the behavior of all external components (such as kernel, nlp, etc.). If something is missing, add it.
• API definition:
  • We use API FIRST design. i.e. firstly we define the swagger of the API and then we build the routing of the API using the swagger directly from expressjs and express-openapi.
  • We use OpenApi v3 for swagger definition
  • We generate the client of the API and the related models automatically after a change in the swagger file.
    • Client package is published on the fly to the correspondant npm registry (github during the development phase and npm for master and release), so its code never exists in the server repository.
    • Models package is updated in the server repository, but just using the definitions in the swagger, no extra code should be written.
  • Swagger file must be called swagger.yml and must be created in the root of the server, at the same level of its package.json.
  • Each server that needs a client must have a client folder with just the package.json of the client, the rest of the code is autogenerated by aura’s CI system.
• HTTP requests: we use superagent library to handle HTTP request, both in our generated API clients and in those done directly from the servers. Currently we use version 5.2.2, but we are moving to version 8 in following releases.
  • request and request-promise are strongly prohibited.

Work on a main branch

When you work on a main branch, the libraries are published on Github.

To install the dependencies of a package, you need the following steps:

• Create a Github development token with package read permission.

• Configure SSO for this token.

• Configure your .npmrc file in your root directory:

//npm.pkg.github.com/:_authToken=XXX

@telefonica:registry=https://npm.pkg.github.com

Work on a master branch

When you work on a master branch, the libraries are published in npm.

To install the dependencies of a package, you need the following steps:

• Request a npm token from your team.

• Configure your .npmrc file in your root directory:

//registry.npmjs.org/:_authToken=XXXX

@telefonica:registry=https://npm.pkg.github.com