docs/developer-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 A1 Developer Guide
   5 ==================
   6
   7 .. contents::
   8    :depth: 3
   9    :local:
  10
  11 Tech Stack
  12 ----------
  13
  14 -  OpenAPI3
  15 -  Connexion
  16 -  Flask with Gevent serving
  17 -  Python3.8
  18
  19 Version bumping A1
  20 ------------------
  21
  22 This project follows semver. When changes are made, the versions are in:
  23
  24 1) ``docs/release-notes.rst``
  25
  26 2) ``setup.py``
  27
  28 3) ``container-tag.yaml``
  29
  30 4) ``integration_tests/a1mediator/Chart.yaml``
  31
  32 5) ``a1/openapi.yaml`` (this is an API version, not a software version; no need to bump on patch changes)
  33
  34 6) in the ric-plt repo that contains a1 helm chart, ``values.yaml``, ``Chart.yml``
  35
  36
  37 Version bumping RMR
  38 -------------------
  39
  40 As of 2020/02/13, A1 (Dockerfile), Dockerfile-Unit-Test,  and all three integration test receivers use a base image from o-ran-sc.
  41 The rmr version is in that base image.
  42 When version changes are made in that image, rebuilding those 5 containers in the A1 repo will pick it up (or just A1 itself for prod usage).
  43
  44 However, there are two items in this repo that must be kept in sync:  ``rmr-version.yaml``, which  controls what rmr gets installed for unit testing in Jenkins, and ``integration_tests/install_rmr.sh`` which is a useful script for a variety of local testing.
  45
  46 Version bumping Python
  47 ----------------------
  48
  49 If you want to update the version of python itself (ie just done from 37 to 38):
  50
  51 1) ``Dockerfile``
  52
  53 2) ``Dockerfile-Unit-Test``
  54
  55 3) ``tox.ini``
  56
  57 Unit Testing
  58 ------------
  59
  60 Note,  before this will work, for the first time on the machine running the tests, run ``./install_deps.sh``. This is only needed once on the machine.
  61 Also, this requires the python packages ``tox`` and ``pytest``.
  62
  63 ::
  64
  65    tox
  66    open htmlcov/index.html
  67
  68 Alternatively, you can run the unit tests in Docker (this is somewhat less nice because you don't get the pretty HTML)
  69
  70 ::
  71
  72    docker build  --no-cache -t a1test:latest -f Dockerfile-Unit-Test
  73
  74 Integration testing
  75 -------------------
  76
  77 This tests A1’s external API with three test receivers. This requires docker, kubernetes and helm.
  78
  79 Build all the images:
  80
  81 ::
  82
  83     docker build  -t a1:latest .
  84     cd integration_tests/testxappcode
  85     docker build -t delayreceiver:latest -f Dockerfile-delay-receiver .
  86     docker build -t queryreceiver:latest -f Dockerfile-query-receiver .
  87     docker build -t testreceiver:latest  -f Dockerfile-test-receiver  .
  88
  89
  90 Then, run all the tests from the root (this requires the python packages ``tox``, ``pytest``, and ``tavern``).
  91
  92 ::
  93
  94    tox -c tox-integration.ini
  95
  96 This script:
  97 1. Deploys 3 helm charts (5 containers) into a local kubernetes installation
  98 2. Port forwards a pod ClusterIP to localhost
  99 3. Uses “tavern” to run some tests against the server
 100 4. Barrages the server with apache bench
 101 5. Tears everything down