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 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.7
  18
  19 Version bumping
  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 As of 2020/02/13, A1 (Dockerfile), Dockerfile-Unit-Test,  and all three integration test receivers use a base image from o-ran-sc.
  40 The rmr version is in that base image.
  41 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).
  42
  43 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.
  44
  45 Version bumping python itself
  46 -----------------------------
  47 If you want to update the version of python itself (ie just done from 37 to 38):
  48
  49 1) ``Dockerfile``
  50
  51 2) ``Dockerfile-Unit-Test``
  52
  53 3) ``tox.ini``
  54
  55 Unit Testing
  56 ------------
  57 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.
  58 Also, this requires the python packages ``tox`` and ``pytest``.
  59
  60 ::
  61
  62    tox
  63    open htmlcov/index.html
  64
  65 Alternatively, you can run the unit tests in Docker (this is somewhat less nice because you don't get the pretty HTML)
  66
  67 ::
  68
  69    docker build  --no-cache -t a1test:latest -f Dockerfile-Unit-Test
  70
  71 Integration testing
  72 -------------------
  73 This tests A1’s external API with three test receivers. This depends on helm+k8s.
  74
  75 Build all the containers:
  76
  77 ::
  78
  79     docker build  -t a1:latest .; cd integration_tests/; docker build  -t testreceiver:latest . -f Dockerfile-test-delay-receiver; docker build -t queryreceiver:latest . -f Dockerfile-query-receiver; cd ..
  80
  81
  82 Then, run all the tests from the root (this requires the python packages ``tox``, ``pytest``, and ``tavern``).
  83
  84 ::
  85
  86    tox -c tox-integration.ini
  87
  88 This script:
  89 1. Deploys 3 helm charts (5 containers) into a local kubernetes installation
  90 2. Port forwards a pod ClusterIP to localhost
  91 3. Uses “tavern” to run some tests against the server
  92 4. Barrages the server with apache bench
  93 5. Tears everything down