CONTRIBUTING.md

Contribution Guide

This guide will provide you with the tools to start developing on the dSIPRouter platform and contributing back to the community.

Getting Started

First we will get our dev environment setup. We recommend you create a local or cloud hosted VM for your dev environment.

1. Clone the branch you would like to work on and create a feature branch for your changes. In this example we want to add support for Ubuntu 20.04 to the master branch.

   git clone -b master https://github.com/dOpensource/dsiprouter.git /opt/dsiprouter
   cd /opt/dsiprouter
   git checkout -b feature-ubuntu-20.04

2. Install dSIPRouter with dev options. You may need different flags depending on where you deploy (servernat, etc..)

   ./dsiprouter.sh install -all -servernat -with_dev

   This will run through the entire install process, then configure your git environment for the dsiprouter repo. For the rest of this walkthrough assume your starting location is in project root (default /etc/dsiprouter).

3. Make your changes.. Then prior to commit make sure you reset any defaults in settings.py (this won't be needed in the future). If you didn't make any changes to settings.py then store a copy and revert it before committing.

   cp -f gui/settings.py /var/backups/dsiprouter/settings.py
   git checkout HEAD -- gui/settings.py

   If you did make any changes to settings.py then you will have manually reset the defaults before committing. We recommend storing a backup of the current settings.py, resetting it, then merging your changes manually, something like this:

   cp -f gui/settings.py /var/backups/dsiprouter/settings.py
   git checkout HEAD -- gui/settings.py
   diff gui/settings.py /var/backups/dsiprouter/settings.py
   vim gui/settings.py

4. Then commit, and push the changes to your feature branch.

   git add -A
   git commit
   git push

   This will run the git hooks setup earlier and automatically do the following:

   • update python dependencies in requirements.txt
   • update the changelog doc
   • update the contributors doc
   • resolve git references in your commit message

   If your committing to a different remote (i.e. not origin), then you need to let our hooks know beforehand. This is useful if you forked dsiprouter, or you have a secondary upstream/downstream remote:

   git commit --remote=upstream
   git push upstream

5. Create a Pull Request on Github (or Merge Request if on gitlab). See the Github Docs for more information.

6. Reset your dsiprouter settings

   cp -f /var/backups/dsiprouter/settings.py gui/settings.py

Core Architecture Principles

• Installation should be less then 10 minutes
• Someone with basic SIP knowledge should be able to configure it and place a test call within 10 minutes
• The API structure should follow the Web URI

File Structure

Modules

Structure

Our module architecture has been loosely defined for a while, but we now want to define the structure and start moving all modules into this structure. Each module should have these components:

Component	Location	Purpose
module.js	gui/static/js/	Contains the UI Javascript for a module
module.css	gui/static/css/	Contains the Cascading Style Sheets for a module
module.py	gui/modules/module	Contains the Python scripts

For example, this is what the "Domain" module looks like:

Component	Location	Purpose
domain.js	gui/static/js/	Contains the UI Javascript for a module
domain.css	gui/static/css/	Contains the Cascading Style Sheets for a module
domain*.py	gui/modules/domain/	Contains the Python scripts
domain*.sql	gui/modules/domain/	SQL Scripts for installing the database table structure fro the module

Packaging

Modules not installed during dSIPRouter install should be packaged in a zipfile with an install script. The install script should place the components defined in the Structure section into their proper locations.

Auto-discovery

Modules should be automatically discoverable. This means that a new module should become automatically available from the UI without restarting the UI

API Structure

Todo: Assigned to Tyler

Useability

• Web GUI
• REST API
• CLI Commands

Development Environment

dsiprouter.sh

• Do not put platform specific commands in this file. Use the component/OS distribution/version.sh file to place those commands.

For example, if we need to install the Letsencrypt OS package so that it can be used for Kamailio on debian, then you would place it in the kamailio/debian/9.sh and kamailio/debian/10.sh file