Contributing to Aura

• 1: Access to Github repositories
• 2: Contributing with code
• 3: Migrate a git folder
• 4: Manage Jira
• 5: Source Folder Layout

$ git clone git@github.com:Telefonica/aura-bot-platform.git
$ cd aura-bot-platform
$ git checkout main/my-feature#12345

$ cd aura-bot-platform
$ git checkout main/my-feature#12345
$ git pull origin main/my-feature#12345

$ git checkout -b feat/my-new-feature

<type>(<optional scope>): <description>

[optional body]

1 - Access to Github repositories

Request access to Aura repositories in Github

How can L-CDO developers access to Github repositories?

All local CDO developers are enrolled into a specific team in Github for each country, which provides the access to the relevant Aura repositories in Github, such as https://github.com/Telefonica/aura-bot-libraries.

To gain access to your local CDO team in Github, you have to fulfill the following requirements:

1. Having a personal account in Github.

2. Two factor authentication (2FA) enabled for the account.

3. Your personal profile page in Github must fulfill the following requisites:

   3.1. It must include a personal image, not an avatar, distinct from the one Github assigns by default.

   3.2. It must include your name and surname.

   3.3. It must include a “@telefonica.com” as the public personal email account associated to the Github profile.

ℹ️ Please, have a look at https://github.com/Korreca as an example of a valid personal profile page in Github.

ℹ️ You can also check the document Configuring two-factor authentication.

Once the previous requirements have been successfully fulfilled, please send a message to the “[APE] AURA-LCDO-XY-GENERAL” chat in Microsoft Teams (where “XY” should be substituted by the 2 letters code associated to your country) requesting access to the Aura repositories in Github.

A member of the APE team will request your registration into the Telefónica organization in Github. Afterwards, you will receive an email message including your personal invitation to be registered in it.

Once you have been included in the Telefónica organization in Github, a member of the APE team will enroll yourself in the appropriate “Aura Development XY” (where “XY” should be substituted by the 2 letters code associated to your country) which will grant you access to all the relevant Aura repositories in Github.

2 - Contributing with code

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

3 - Migrate a git folder

Migrate a git folder to a new repository

Move files with history

This document explains how to migrate the history of the files to the new repository (that could or could not be desirable).

This process tells how to move a part of a repository (folder) to a new repository, maintaining the history of the files. A new fresh copy of the origin repository is required, as it will not be usable anymore.

These commands will prepare a repo with only the commits from a specific folder (removing anything else):

# Clone a fresh copy of origin repo and enter into it
git clone <giturl-repoA>
cd <repoA>
# Optional, to avoid pushing to the wrong remote repository
git remote rm origin
# From the repo source, remove all the files and history outside the folder
git filter-branch --subdirectory-filter <folder-name> -- --all

Now, we can import in the new repository following these steps:

# Optional, clone a fresh copy of destination repo (or could use a previously existing one) and enter into it
git clone <giturl-repoB>
cd <repoB>
# Add a new remote pointing to local path with repo A
git remote add repoA <local-path-repoA>
# Pull from previous local repository the dialog files, branch master (replace if using a different one)
git pull repoA master --allow-unrelated-histories
# Optional, create a new branch to merge into
git checkout -b <destination-branch>
# Remove local remote, not required anymore
git remote rm repoA

4 - Manage Jira

Guidelines for Jira management

Analysis

Development

FAQs

What to do if you have to integrate with another development team?

If, for example, we are going to integrate something with the Cognitive Team, such as the new suggestions API, we will be talking to them integrated in the same team all the time.

But the moment we need them to pass us their swagger, whether their component is deployed or the update deployed, we will give them a task to do so.

How to upload the code to git?

To upload the code to git, Pull Request to master or release/* is performed depending on the moment.

We upload it when we have finished, with a disclaimer: if we are dependent on other teams that are going to call our API or use the modification for something, we will be especially careful and upload the changes when they are necessary and not to break their development.

Do I have to notify QA at the end of coding?

Yes, you have to notify them when a new feature or a fix is deployed in the corresponding environment.

If it is bug or complete US, passing them to resolved they are already warned, but I like more to give them a touch and tell them.

In addition to when we upload the code, I like to share the analysis and design pages with them, because the discussions are usually very productive.

Should we notify someone about the generated documentation?

We must notify María Eugenia, who is the documentary maker. The ideal is to leave indicated in each US/Bug which documentation has been modified with its development. María Eugenia takes the doc from aura-docs, from Confluence or from the corresponding repo and includes it in the product versions.

How do the tasks change states?

We must pass the US/bugs from “new” -> “in progress” -> “code review” -> “resolved”. Tasks in the “resolved” state go “closed” when QA validates them.

How do I change version of component or library?

We do this process with each release or phase change. The future is that everything is done automatically by Jenkins.

5 - Source Folder Layout

Source folder layout

Introduction

The repository aura-bot-platform has a folder layout inside src folder, to organize the code according to functionality groups.

In src root folder, only main files should be placed, such as index.ts, or main server file server.ts (app.ts in aura-bot).

src/ sub-folders

src/bots

Currently, only the file aura-bot.ts is included here, that is the main ActivityHandler (kind of replace of previous UniversalBot).

In a near future, more Bot Builder adapters could be located here.

src/config

In this folder, files that load configurations are included. These files are required in other places, such as channel configuration, env vars, etc.

src/db

In this folder, files that manage and connect to databases are located, such as MongoDB.

src/events

Files handling events (such as ModuleObserver subclasses) should be placed in this folder.

src/dialogs

This folder contains aura-bot main dialog and custom prompts, as use case dialogs will be located in libraries, loaded as dependencies.

src/make

In this folder, the code related with joining all the library-specific data with global ones is included, corresponding to the make-up process.

src/middlewares

This folder contains abstract middleware base classes, and specific middleware implementation (final classes).

src/middlewares/recognizers

This folder contains all the recognizers, such as nlp-recognizer-middleware, aura-command-recognizer-middleware, etc.

src/models

Files located within this folder will have exported types and interfaces required in different parts of the code (types and interfaces required only within a file could be self-contained).

src/modules

This folder contains independent code blocks, that could be exported as a reusable packages if required in different components, such as cache manager, locale manager, etc.

src/plugin

This folder contains the modules in charge of loading plugins: charging dialogs, middlewares, delivery configuration for these components, etc.

src/routing

Here, code related with intent-to-dialog routing is located, as this is not part of Bot Builder anymore.

src/utils

This folder contains utility classes and methods that are not part or any other block. We should maintain this folder organized and tidy, to avoid lots of unspecific files.