Aura – contributing

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Request access to Aura repositories in Github

Steps for L-CDO developers willing to access to aura-bot and aura-nlp Github repositories

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:

Having a personal account in Github.
Two factor authentication (2FA) enabled for the account.
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.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

How to write code in Aura Bot global repositories

Guidelines for developers willing to contribute to Aura Bot global repositories writing code

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:

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

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Contributing to Aura

Discover how to contribute to Aura Platform global repositories

Introduction

The aim of this document is to establish common minimum rules for developers willing to contribute to Aura Global repositories:

How to request access to Aura repositories in Github
How to write code in aura-bot global repositories
How to migrate a git folder to a new repository
How to manage user stories and tasks in JIRA
Types of branches and guidelines for the generation of a new branch

The target audience of the document are developers of global and local teams contributing to Aura Global repositories:

aura-bot developers
aura-bridge developers
aura-services-api developers
…

⚠️ This document assumes that the developers already have permissions to access Telefónica organization in Github.

Branches used by Aura

Aura uses 2 different types of branches:

Eternal or pseudo eternal branches

These are protected branches, that MUST be always deployable in a given environment.

Protected means:

Only code owners can push code to them
All changes MUST be pushed through a pull request, that MUST pass the continuous integration checks and count on, at least, 2 approval reviews of code owners.

These branches are:

master: it holds next release code. It MUST be deployable in the global development environments.
main/*: it holds the development of a unique User Story or set of User Stories.
release/*: it holds the given release code. It MUST be deployable in global development environments and also in PRE and PRO of the OBs involved in this release developments.
hotfix/*: it holds the resolution of an issue or set of issues happening in a pre or pro environment.

Temporary branches

As any change in eternal branches MUST be done though a Pull Request, it means that they must be done in a temporary or feature branch.

These branches are usually named after the type of change they are going to hold: feat/my-new-feature or fix/fixing-that.

This format is <type>/<description>[#issue_number] where:

type is one of feat, fix, chore and docs
description should be a short description, dash-separated words, of the change. If using Jira as issue manager, add the number of the issue being resolved after a #.

Process for generating a new branch

First of all, clone the repository and choose an eternal branch as base branch for your feature:

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

Or update the base eternal branch for your feature:

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

Then, create a new branch:

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

Some recommendations should be considered:

Split your changes in small tasks (max 1 day per task)
Use a feature (feat, fix, chore, …) branch per task
Do small commits with spotted functionality
Do small PRs with all the code of a given task
When asking a PR remember to include an explanation of the why, how, what has been done in the PR, in order to help reviewers to understand the change.

Commit messages format

The format followed in Aura is the one described in Conventional Commits.

These messages are used to handle the version of each Aura component so it is very important to follow these rules.

NOTE: Pull Requests including commits without this format will be rejected.

Format

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

[optional body]

Valid types: feat, fix, chore, docs
Valid scopes:
- global, can be omitted, if affects all the packages or it’s a basic change.
- the affected package in a multipackage repository.
- the affected library, plugin or dialog in library repository.
- if it affects a concrete feature in the repository: logging, kpis, authentication, etc.
- it can also be omitted in global cases, in minor changes, etc.
Description: indicative sentence in lower case.
Body: only if description field is not enough to understand the changes

Folder layout

In general, all the repositories containing typescript code should have an src folder with all the typescript source files there, and those source files will be transpiled into javascript into folder lib.

Unit tests

Currently aura-bot team is moving to Jest as unittest runner, so a couple of versions of unittest can be found:

Projects running with mocha, such as aura-bot-platform.

Test files should be included in the same folder as the files to test, with a trailing .spec.ts in the file name (these files should be .npmignore, to avoid being in the final package).

Test assets required for tests (.json files, images, .env files, etc.) will be placed in a test folder (that should be .npmignore too), so they will be available for typescript/javascript files by getting the path ../test or similar.

Projects running with jest, such as aura-mocks-server.

There will be a specific folder called test, at the same level than src and that will hold all the unit tests following the same structure than src. As with mocha tests, they must be ignored in the production transpilation and the files published in npm.

More about src/ folder layout in aura-bot-platform can be found in this file.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Migrate a git folder to a new repository

Learn how to migrate a folder within a Git repository to another 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

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Guidelines for Jira management

Learn how to handle user stories and tasks in Jira

Analysis

Description	Tool	State
Create Analysis Task	JIRA	[X]
Create Analysis Documentation	Confluence	[X]
. . . Use cases		[X]
. . . Data model		[X]
. . . Component architecture		[X]
Create “doubt repository”	JIRA/Confluence	[X]
—
Have all doubts been resolved?		[X]
Has the result of the analysis been presented?		[X]
Have several alternatives been evaluated?		[X]
Has the chosen option been agreed upon?		[X]
Chosen solution meets the performance requirements?		[X]

Development

Description	Tool	State
Create branch “feat” for each task	GIT	[X]
Create unit tests	GIT	[X]
Create Documentation (README)	GIT	[X]
Add lint rules (standard)	GIT	[X]
Create jenkins tasks (if they don’t exist)	JENKINS	[X]
Check for missing jenkins tasks	JENKINS	[X]
—
Does the code pass all unit tests?		[X]
Do the unit tests cover 80% coverage?		[X]
Does the code comply with the lint rules?		[X]
Have the Jenkinsfile and pipelines been checked?		[X]
Is the README documentation up to date?		[X]

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.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Source folder layout

Description of Aura Bot Platform src/ repository

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.