docs/jjb/lf-python-jobs.rst

   1 ###########
   2 Python Jobs
   3 ###########
   4
   5 Job Groups
   6 ==========
   7
   8 {project-name}-python-jobs
   9 --------------------------
  10
  11 Jobs for Python projects using Gerrit.
  12
  13 :Includes:
  14
  15     - gerrit-tox-verify
  16
  17 {project-name}-github-python-jobs
  18 ---------------------------------
  19
  20 Jobs for Python projects using GitHub.
  21
  22 :Includes:
  23
  24     - github-tox-verify
  25
  26
  27 Macros
  28 ======
  29
  30 lf-tox-install
  31 --------------
  32
  33 Runs a shell script that installs tox in a Python virtualenv.
  34
  35 :Required Parameters:
  36
  37     :python-version: Base Python version to use in the virtualenv. For example
  38         python2 or python3.
  39
  40
  41 Job Templates
  42 =============
  43
  44 Python Sonar with Tox
  45 ---------------------
  46
  47 Sonar scans for Python based repos. This job will perform a tox call which
  48 runs the coverage command to gather tests results. These test results get
  49 published back into Sonar after running the Sonar goals.
  50
  51 To get the Sonar coverage results, tox.ini needs to exist and configured
  52 with coverage commands to run.
  53
  54 The coverage commands define the code that gets executed by the test suites.
  55 It does not guarantee that the code tests executed properly, but it will help
  56 pointing out the code that is not tested at all.
  57
  58 For example:
  59
  60 .. code-block:: bash
  61
  62     [testenv:py27]
  63     commands =
  64             coverage run --module pytest --junitxml xunit-results.xml
  65             coverage xml --omit=".tox/py27/*","tests/*"
  66             coverage report --omit=".tox/py27/*","tests/*"
  67
  68 For more details refer to coverage and sonar documentation:
  69
  70 https://coverage.readthedocs.io/
  71
  72 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
  73
  74 :Template Names:
  75
  76     - {project-name}-tox-sonar
  77     - gerrit-tox-sonar
  78     - github-tox-sonar
  79
  80 :Required parameters:
  81
  82     :build-node: The node to run build on.
  83     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
  84         get configured in defaults.yaml)
  85     :mvn-settings: The name of settings file containing credentials for the project.
  86
  87 :Optional parameters:
  88
  89     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
  90     :build-timeout: Timeout in seconds before aborting build. (default: 60)
  91     :cron: Cron schedule when to trigger the job. This parameter also
  92         supports multiline input via YAML pipe | character in cases where
  93         one may want to provide more than 1 cron timer.  (default: H 11 * * *
  94         to run once a day)
  95     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
  96     :java-version: Version of Java to use for the build. (default: openjdk8)
  97     :mvn-global-settings: The name of the Maven global settings to use for
  98         Maven configuration. (default: global-settings)
  99     :mvn-version: Version of maven to use. (default: mvn33)
 100     :stream: Keyword used to represent a release code-name.
 101         Often the same as the branch. (default: master)
 102     :submodule-recursive: Whether to checkout submodules recursively.
 103         (default: true)
 104     :gerrit_sonar_triggers: Override Gerrit Triggers.
 105
 106 Tox Verify
 107 ----------
 108
 109 Tox runner to verify a project. This job is pyenv aware so if the image
 110 contains an installation of pyenv at /opt/pyenv it will pick it up and run
 111 Python tests with the appropriate Python versions. This job will set the
 112 following pyenv variables before running.
 113
 114 .. code:: bash
 115
 116    export PYENV_ROOT="/opt/pyenv"
 117    export PATH="$PYENV_ROOT/bin:$PATH"
 118
 119 :Template Names:
 120
 121     - {project-name}-tox-verify-{stream}
 122     - gerrit-tox-verify
 123     - github-tox-verify
 124
 125 :Required Parameters:
 126
 127     :build-node: The node to run build on.
 128     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 129         in defaults.yaml)
 130
 131 :Optional Parameters:
 132
 133     :branch: The branch to build against. (default: master)
 134     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 135     :build-timeout: Timeout in seconds before aborting build. (default: 10)
 136     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 137     :python-version: Version of Python to configure as a base in virtualenv.
 138         (default: python3)
 139     :stream: Keyword representing a release code-name.
 140         Often the same as the branch. (default: master)
 141     :submodule-recursive: Whether to checkout submodules recursively.
 142         (default: true)
 143     :tox-dir: Directory containing the project's tox.ini relative to
 144         the workspace. Empty works if tox.ini is at project root.
 145         (default: '')
 146     :tox-envs: Tox environments to run. If blank run everything described
 147         in tox.ini. (default: '')