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 The A1 Mediator is implemented in Python, currently version 3.8, and
  15 depends on these third-party packages and technologies:
  16
  17 - OpenAPI3
  18 - Connexion
  19 - Flask with Gevent serving
  20 - Swagger
  21
  22 Version bumping A1
  23 ------------------
  24
  25 This project follows semver. When the version string changes, these
  26 files must be updated:
  27
  28 #. ``setup.py``
  29 #. ``container-tag.yaml``
  30 #. ``integration_tests/a1mediator/Chart.yaml``
  31 #. ``docs/release-notes.rst``
  32 #. ``a1/openapi.yaml`` But note this is an API version, not a software version; there's no need to bump on non-API changes.
  33 #.  And over in the ric-plt/ric-dep repo that contains the A1 Mediator helm chart, files ``values.yaml`` and ``Chart.yaml``.
  34
  35 It's convenient to use the Python utility `bumpversion` to maintain
  36 the first three items.  After setup (``pip install bumpversion``) you
  37 can change the patch version like this::
  38
  39     bumpversion --verbose patch
  40
  41 Or change the minor version like this::
  42
  43     bumpversion --verbose minor
  44
  45 After the `bumpversion` utility has modified the files, update the
  46 release notes then commit.
  47
  48
  49 Version bumping RMR
  50 -------------------
  51
  52 A1 (Dockerfile), Dockerfile-Unit-Test, and all three integration test
  53 receivers use an Alpine base image and install RMR from a base builder
  54 image.  Must update and rebuild all 5 containers in the A1 repo (or
  55 just A1 itself for production usage).
  56
  57 In addition these items in this repo must be kept in sync:
  58
  59 #. ``rmr-version.yaml`` controls what rmr gets installed for unit
  60    testing in Jenkins
  61 #. ``integration_tests/install_rmr.sh`` is a useful script for a
  62    variety of local testing.
  63
  64 Version bumping Python
  65 ----------------------
  66
  67 If you want to update the version of python; for example this was
  68 recently done to move from 3.7 to 3.8, update these files:
  69
  70 #. ``Dockerfile``
  71 #. ``Dockerfile-Unit-Test``
  72 #. ``tox.ini``
  73
  74 Unit Testing
  75 ------------
  76
  77 Running the unit tests requires the python packages ``tox`` and ``pytest``.
  78
  79 The RMR library is also required during unit tests. If running
  80 directly from tox (outside a Docker container), install RMR using the
  81 script in the integration_tests directory: ``install_rmr.sh``.
  82
  83 Upon completion, view the test coverage like this:
  84
  85 ::
  86
  87    tox
  88    open htmlcov/index.html
  89
  90 Alternatively, you can run the unit tests in Docker (this is somewhat
  91 less nice because you don't get the pretty HTML)
  92
  93 ::
  94
  95    docker build  --no-cache -f Dockerfile-Unit-Test .
  96
  97 Integration testing
  98 -------------------
  99
 100 This tests A1’s external API with three test receivers. This requires
 101 docker, kubernetes and helm.
 102
 103 Build all the images:
 104
 105 ::
 106
 107     docker build  -t a1:latest .
 108     cd integration_tests/testxappcode
 109     docker build -t delayreceiver:latest -f Dockerfile-delay-receiver .
 110     docker build -t queryreceiver:latest -f Dockerfile-query-receiver .
 111     docker build -t testreceiver:latest  -f Dockerfile-test-receiver  .
 112
 113
 114 Then, run all the tests from the root (this requires the python packages ``tox``, ``pytest``, and ``tavern``).
 115
 116 ::
 117
 118    tox -c tox-integration.ini
 119
 120 This script:
 121
 122 #. Deploys 3 helm charts (5 containers) into a local kubernetes installation
 123 #. Port forwards a pod ClusterIP to localhost
 124 #. Uses “tavern” to run some tests against the server
 125 #. Barrages the server with Apache bench
 126 #. Tears everything down