Contributing to Aura

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.