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 6) ``a1/openapi.yaml`` (this is an API version, not a software version; no need to bump on patch changes)
  33
  34 7) in the it/dep repo that contains a1 helm chart, ``values.yaml``, ``Chart.yml``
  35
  36
  37 Version bumping rmr
  38 --------------------
  39 rmr is a critical dependency of A1. Bumping the rmr version dependency requires changes in:
  40
  41 1) ``Dockerfile``
  42
  43 2) ``Dockerfile-Unit-Test``
  44
  45 3) ``integration_tests/Dockerfile-test-delay-receiver``
  46
  47 4) ``integration_tests/Dockerfile-query-receiver``
  48
  49 5) ``rmr-version.yaml``
  50
  51 rmr-python is the python binding to rmr . Installing rmr per the above does not install it.
  52 Bumping the rmr python version dependency requires changes in:
  53
  54 1) ``setup.py``
  55
  56 2) ``integration_tests/Dockerfile-test-delay-receiver``
  57
  58 3) ``integration_tests/Dockerfile-query-receiver``
  59
  60 Run the integration tests after attempting this.
  61
  62 Unit Testing
  63 ------------
  64 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.
  65 Also, this requires the python packages ``tox`` and ``pytest``.
  66
  67 ::
  68
  69    tox
  70    open htmlcov/index.html
  71
  72 Alternatively, you can run the unit tests in Docker (this is somewhat less nice because you don't get the pretty HTML)
  73
  74 ::
  75
  76    docker build  --no-cache -t a1test:latest -f Dockerfile-Unit-Test
  77
  78 Integration testing
  79 -------------------
  80 This tests A1’s external API with three test receivers. This depends on helm+k8s.
  81
  82 Build all the containers:
  83
  84 ::
  85
  86     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 ..
  87
  88
  89 Then, run all the tests from the root (this requires the python packages ``tox``, ``pytest``, and ``tavern``).
  90
  91 ::
  92
  93    tox -c tox-integration.ini
  94
  95 This script:
  96 1. Deploys 2 helm charts (4 containers) into a local kubernetes installation
  97 2. Port forwards a pod ClusterIP to localhost
  98 3. Uses “tavern” to run some tests against the server
  99 4. Barrages the server with apache bench
 100 5. Tears everything down