docs/jjb/lf-python-jobs.rst

   1 ###########
   2 Python Jobs
   3 ###########
   4
   5 Job Groups
   6 ==========
   7
   8 .. include:: ../job-groups.rst
   9
  10 Below is a list of Maven job groups:
  11
  12 .. literalinclude:: ../../jjb/lf-python-job-groups.yaml
  13    :language: yaml
  14
  15
  16 Macros
  17 ======
  18
  19 lf-infra-clm-python
  20 -------------------
  21
  22 Run CLM scanning against a Python project.
  23
  24 :Required Parameters:
  25
  26     :clm-project-name: Project name in Nexus IQ to send results to.
  27
  28 lf-infra-tox-install
  29 --------------------
  30
  31 Install Tox into a virtualenv.
  32
  33 :Required Parameters:
  34
  35     :python-version: Version of Python to install into the Tox virtualenv.
  36         Eg. python2 / python3
  37
  38 lf-tox-install
  39 --------------
  40
  41 Runs a shell script that installs tox in a Python virtualenv.
  42
  43 :Required Parameters:
  44
  45     :python-version: Base Python version to use in the virtualenv. For example
  46         python2 or python3.
  47
  48
  49 Job Templates
  50 =============
  51
  52 Python XC CLM
  53 -------------
  54
  55 CLM scans for Python based repos. This job will call the Nexus IQ CLI
  56 directly to run the scans.
  57
  58 A new credential named "nexus-iq-xc-clm" needs to exist in the Jenkins credentials.
  59 The credential should contain the username and password to access Nexus
  60 IQ Server.
  61
  62 :Template Names:
  63
  64     - {project-name}-python-clm-{stream}
  65     - gerrit-python-xc-clm
  66     - github-python-xc-clm
  67
  68 :Comment Trigger: run-clm
  69
  70 :Required parameters:
  71
  72     :build-node: The node to run build on.
  73     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
  74         get configured in defaults.yaml)
  75
  76 :Optional parameters:
  77
  78     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
  79     :nexus-iq-cli-version: Nexus IQ CLI package version to download and use.
  80         (default: 1.44.0-01)
  81     :nexus-iq-namespace: Insert a namespace to project AppID for projects that
  82         share a Nexus IQ system to avoid project name collision. We recommend
  83         inserting a trailing - dash if using this parameter.
  84         For example 'odl-'. (default: '')
  85     :build-timeout: Timeout in minutes before aborting build. (default: 60)
  86     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
  87     :java-version: Version of Java to use for the build. (default: openjdk8)
  88     :pre-build-script: Shell script to execute before the CLM builder.
  89         For example, install prerequisites or move files to the repo root.
  90         (default: a string with a shell comment)
  91     :stream: Keyword used to represent a release code-name.
  92         Often the same as the branch. (default: master)
  93     :submodule-recursive: Whether to checkout submodules recursively.
  94         (default: true)
  95     :submodule-timeout: Timeout (in minutes) for checkout operation.
  96         (default: 10)
  97     :submodule-disable: Disable submodule checkout operation.
  98         (default: false)
  99     :gerrit_clm_triggers: Override Gerrit Triggers.
 100     :gerrit_trigger_file_paths: Override file paths which used to filter which
 101         file modifications will trigger a build. Refer to JJB documentation for
 102         "file-path" details.
 103         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 104
 105
 106 Python Sonar with Tox
 107 ---------------------
 108
 109 Sonar scans for Python based repos. This job invokes tox to run tests and
 110 gather coverage statistics from the test results, then invokes Maven to
 111 publish the results to a Sonar server.
 112
 113 To get the Sonar coverage results, file tox.ini must exist and contain coverage
 114 commands to run.
 115
 116 The coverage commands define the code that gets executed by the test suites.
 117 Checking coverage does not guarantee that the tests execute properly, but it
 118 identifies code that is not executed by any test.
 119
 120 This job reuses the Sonar builder used in Java/Maven projects which runs maven
 121 twice. The first invocation does nothing for Python projects, so the job uses
 122 the goal 'validate' by default. The second invocation publishes results using
 123 the goal 'sonar:sonar' by default.
 124
 125 For example:
 126
 127 .. code-block:: bash
 128
 129     [testenv:py27]
 130     commands =
 131             coverage run --module pytest --junitxml xunit-results.xml
 132             coverage xml --omit=".tox/py27/*","tests/*"
 133             coverage report --omit=".tox/py27/*","tests/*"
 134
 135 For more details refer to coverage and sonar documentation:
 136
 137 https://coverage.readthedocs.io/
 138
 139 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
 140
 141 :Template Names:
 142
 143     - {project-name}-tox-sonar
 144     - gerrit-tox-sonar
 145     - github-tox-sonar
 146
 147 :Comment Trigger: run-sonar
 148
 149 :Required parameters:
 150
 151     :build-node: The node to run build on.
 152     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 153         get configured in defaults.yaml)
 154     :mvn-settings: The name of the settings file with credentials for the project.
 155
 156 :Optional parameters:
 157
 158     :branch: Git branch, should be master (default: master)
 159     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 160     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 161     :cron: Cron schedule when to trigger the job. This parameter also
 162         supports multiline input via YAML pipe | character in cases where
 163         one may want to provide more than 1 cron timer.  (default: H 11 * * *
 164         to run once a day)
 165     :disable-job: Whether to disable the job (default: false)
 166     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 167     :github-url: URL for Github. (default: https://github.com)
 168     :java-version: Version of Java to use for the build. (default: openjdk8)
 169     :mvn-global-settings: The name of the Maven global settings to use for
 170     :mvn-goals: The Maven goal to run first. (default: validate)
 171     :mvn-version: Version of maven to use. (default: mvn35)
 172     :pre-build-script: Shell script to execute before the Sonar builder.
 173         For example, install prerequisites or move files to the repo root.
 174         (default: a string with a comment)
 175     :python-version: Python version (default: python2)
 176     :sonar-mvn-goal: The Maven goal to run the Sonar plugin. (default: sonar:sonar)
 177     :stream: Keyword used to represent a release code-name.
 178         Often the same as the branch. (default: master)
 179     :submodule-recursive: Whether to checkout submodules recursively.
 180         (default: true)
 181     :submodule-timeout: Timeout (in minutes) for checkout operation.
 182         (default: 10)
 183     :submodule-disable: Disable submodule checkout operation.
 184         (default: false)
 185     :gerrit_sonar_triggers: Override Gerrit Triggers.
 186     :gerrit_trigger_file_paths: Override file paths which used to filter which
 187         file modifications will trigger a build. Refer to JJB documentation for
 188         "file-path" details.
 189         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 190
 191
 192 Tox Verify
 193 ----------
 194
 195 Tox runner to verify a project on creation of a patch set.
 196 This job is pyenv aware so if the image contains an installation of pyenv
 197 at /opt/pyenv it will pick it up and run Python tests with the appropriate
 198 Python versions. This job will set the following pyenv variables before running.
 199
 200 .. code:: bash
 201
 202    export PYENV_ROOT="/opt/pyenv"
 203    export PATH="$PYENV_ROOT/bin:$PATH"
 204
 205 :Template Names:
 206
 207     - {project-name}-tox-verify-{stream}
 208     - gerrit-tox-verify
 209     - github-tox-verify
 210
 211 :Comment Trigger: recheck|reverify
 212
 213 :Required Parameters:
 214
 215     :build-node: The node to run build on.
 216     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 217         in defaults.yaml)
 218
 219 :Optional Parameters:
 220
 221     :branch: The branch to build against. (default: master)
 222     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 223     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 224     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 225     :pre-build-script: Shell script to execute before the Tox builder.
 226         For example, install prerequisites or move files to the repo root.
 227         (default: a string with a shell comment)
 228     :python-version: Version of Python to configure as a base in virtualenv.
 229         (default: python3)
 230     :stream: Keyword representing a release code-name.
 231         Often the same as the branch. (default: master)
 232     :submodule-recursive: Whether to checkout submodules recursively.
 233         (default: true)
 234     :submodule-timeout: Timeout (in minutes) for checkout operation.
 235         (default: 10)
 236     :submodule-disable: Disable submodule checkout operation.
 237         (default: false)
 238     :tox-dir: Directory containing the project's tox.ini relative to
 239         the workspace. Empty works if tox.ini is at project root.
 240         (default: '')
 241     :tox-envs: Tox environments to run. If blank run everything described
 242         in tox.ini. (default: '')
 243     :gerrit_trigger_file_paths: Override file paths used to filter which
 244         file modifications will trigger a build. Refer to JJB documentation for
 245         "file-path" details.
 246         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 247
 248
 249 Tox Merge
 250 ---------
 251
 252 Tox runner to verify a project after merge of a patch set.
 253 This job is pyenv aware so if the image contains an installation of pyenv
 254 at /opt/pyenv it will pick it up and run Python tests with the appropriate
 255 Python versions. This job will set the following pyenv variables before running.
 256
 257 .. code:: bash
 258
 259    export PYENV_ROOT="/opt/pyenv"
 260    export PATH="$PYENV_ROOT/bin:$PATH"
 261
 262 :Template Names:
 263
 264     - {project-name}-tox-merge-{stream}
 265     - gerrit-tox-merge
 266     - github-tox-merge
 267
 268 :Comment Trigger: remerge
 269
 270 :Required Parameters:
 271
 272     :build-node: The node to run build on.
 273     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 274         in defaults.yaml)
 275
 276 :Optional Parameters:
 277
 278     :branch: The branch to build against. (default: master)
 279     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 280     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 281     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 282     :pre-build-script: Shell script to execute before the CLM builder.
 283         For example, install prerequisites or move files to the repo root.
 284         (default: a string with only a comment)
 285     :python-version: Version of Python to configure as a base in virtualenv.
 286         (default: python3)
 287     :stream: Keyword representing a release code-name.
 288         Often the same as the branch. (default: master)
 289     :submodule-recursive: Whether to checkout submodules recursively.
 290         (default: true)
 291     :submodule-timeout: Timeout (in minutes) for checkout operation.
 292         (default: 10)
 293     :submodule-disable: Disable submodule checkout operation.
 294         (default: false)
 295     :tox-dir: Directory containing the project's tox.ini relative to
 296         the workspace. Empty works if tox.ini is at project root.
 297         (default: '')
 298     :tox-envs: Tox environments to run. If blank run everything described
 299         in tox.ini. (default: '')
 300     :gerrit_trigger_file_paths: Override file paths used to filter which
 301         file modifications will trigger a build. Refer to JJB documentation for
 302         "file-path" details.
 303         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit