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 pyrmr
  46 ---------------------
  47 rmr-python is the python binding to rmr . Installing rmr per the above does not install it.
  48 Bumping the rmr python version is done via ``setup.py``
  49
  50 Version bumping python itself
  51 -----------------------------
  52 If you want to update the version of python itself (ie just done from 37 to 38):
  53
  54 1) ``Dockerfile``
  55
  56 2) ``Dockerfile-Unit-Test``
  57
  58 3) ``tox.ini``
  59
  60 Unit Testing
  61 ------------
  62 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.
  63 Also, this requires the python packages ``tox`` and ``pytest``.
  64
  65 ::
  66
  67    tox
  68    open htmlcov/index.html
  69
  70 Alternatively, you can run the unit tests in Docker (this is somewhat less nice because you don't get the pretty HTML)
  71
  72 ::
  73
  74    docker build  --no-cache -t a1test:latest -f Dockerfile-Unit-Test
  75
  76 Integration testing
  77 -------------------
  78 This tests A1’s external API with three test receivers. This depends on helm+k8s.
  79
  80 Build all the containers:
  81
  82 ::
  83
  84     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 ..
  85
  86
  87 Then, run all the tests from the root (this requires the python packages ``tox``, ``pytest``, and ``tavern``).
  88
  89 ::
  90
  91    tox -c tox-integration.ini
  92
  93 This script:
  94 1. Deploys 2 helm charts (4 containers) into a local kubernetes installation
  95 2. Port forwards a pod ClusterIP to localhost
  96 3. Uses “tavern” to run some tests against the server
  97 4. Barrages the server with apache bench
  98 5. Tears everything down