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 Python 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 Runs 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 Installs Tox into a virtualenv.
  32
  33 :Required Parameters:
  34
  35     :python-version: Version of Python to invoke the pip install of the tox-pyenv
  36         package that creates a virtual environment, either "python2" or "python3".
  37
  38 lf-infra-tox-run
  39 ----------------
  40
  41 Creates a Tox virtual environment and invokes tox.
  42
  43 :Required Parameters:
  44
  45     :parallel: Boolean. If true use detox (distributed tox);
  46         else use regular tox.
  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
  59 credentials.  The credential should contain the username and password
  60 to access Nexus 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** post a comment with the trigger to launch
  69     this job manually. Do not include any other text or vote in the
  70     same comment.
  71
  72 :Required parameters:
  73
  74     :build-node: The node to run build on.
  75     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
  76         get configured in defaults.yaml)
  77
  78 :Optional parameters:
  79
  80     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
  81     :nexus-iq-cli-version: Nexus IQ CLI package version to download and use.
  82         (default: 1.44.0-01)
  83     :nexus-iq-namespace: Insert a namespace to project AppID for projects that
  84         share a Nexus IQ system to avoid project name collision. We recommend
  85         inserting a trailing - dash if using this parameter.
  86         For example 'odl-'. (default: '')
  87     :build-timeout: Timeout in minutes before aborting build. (default: 60)
  88     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
  89     :java-version: Version of Java to use for the build. (default: openjdk8)
  90     :pre-build-script: Shell script to execute before the CLM builder.
  91         For example, install prerequisites or move files to the repo root.
  92         (default: a string with a shell comment)
  93     :stream: Keyword used to represent a release code-name.
  94         Often the same as the branch. (default: master)
  95     :submodule-recursive: Whether to checkout submodules recursively.
  96         (default: true)
  97     :submodule-timeout: Timeout (in minutes) for checkout operation.
  98         (default: 10)
  99     :submodule-disable: Disable submodule checkout operation.
 100         (default: false)
 101     :gerrit_clm_triggers: Override Gerrit Triggers.
 102     :gerrit_trigger_file_paths: Override file paths used to filter which file
 103         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 104         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 105
 106
 107 Python Sonar with Tox
 108 ---------------------
 109
 110 Sonar scans for Python based repos. This job invokes tox to run tests
 111 and gather coverage statistics from the test results, then invokes
 112 Maven to publish the results to either a Sonar server or SonarCloud.
 113
 114 **Deprecated**, new projects should use Tox Sonarqube.
 115
 116 To get the Sonar coverage results, file tox.ini must exist and contain
 117 coverage commands to run.
 118
 119 The coverage commands define the code that gets executed by the test
 120 suites.  Checking coverage does not guarantee that the tests execute
 121 properly, but it identifies code that is not executed by any test.
 122
 123 .. comment Start ignoring WriteGoodLintBear
 124
 125 This job reuses the Sonar builders used for Java/Maven projects which
 126 run maven twice. The first invocation does nothing for Python
 127 projects, so the job uses the goal 'validate' by default. The second
 128 invocation publishes results using the goal 'sonar:sonar' by default.
 129
 130 .. comment Stop ignoring
 131
 132 For example:
 133
 134 .. code-block:: bash
 135
 136     [testenv:py27]
 137     commands =
 138             coverage run --module pytest --junitxml xunit-results.xml
 139             coverage xml --omit=".tox/py27/*","tests/*"
 140             coverage report --omit=".tox/py27/*","tests/*"
 141
 142 For more details refer to coverage and sonar documentation:
 143
 144 https://coverage.readthedocs.io/
 145
 146 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
 147
 148 :Template Names:
 149
 150     - {project-name}-tox-sonar
 151     - gerrit-tox-sonar
 152     - github-tox-sonar
 153
 154 :Comment Trigger: **run-sonar** post a comment with the trigger to launch
 155     this job manually. Do not include any other text or vote in the
 156     same comment.
 157
 158 :Required parameters:
 159
 160     :build-node: The node to run build on.
 161     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 162         get configured in defaults.yaml)
 163     :mvn-settings: The name of the settings file with credentials for the project.
 164
 165 .. comment Start ignoring WriteGoodLintBear
 166
 167 :Optional parameters:
 168
 169     :branch: Git branch, should be master (default: master)
 170     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 171     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 172     :cron: Cron schedule when to trigger the job. This parameter also
 173         supports multiline input via YAML pipe | character in cases where
 174         one may want to provide more than 1 cron timer.  (default: H 11 * * *
 175         to run once a day)
 176     :disable-job: Whether to disable the job (default: false)
 177     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 178     :github-url: URL for Github. (default: https://github.com)
 179     :java-version: Version of Java to use for the build. (default: openjdk8)
 180     :mvn-global-settings: The name of the Maven global settings to use
 181     :mvn-goals: The Maven goal to run first. (default: validate)
 182     :mvn-version: Version of maven to use. (default: mvn35)
 183     :parallel: Boolean indicator for tox to run tests in parallel or series.
 184         (default: false, in series)
 185     :pre-build-script: Shell script to execute before the Sonar builder.
 186         For example, install prerequisites or move files to the repo root.
 187         (default: a string with a shell comment)
 188     :python-version: Python version to invoke pip install of tox-pyenv
 189         (default: python2)
 190     :sonarcloud: Boolean indicator to use SonarCloud ``true|false``.
 191         (default: false)
 192     :sonarcloud-project-key: SonarCloud project key. (default: '')
 193     :sonarcloud-project-organization: SonarCloud project organization.
 194         (default: '')
 195     :sonarcloud-api-token: SonarCloud API Token. (default: '')
 196     :sonar-mvn-goal: The Maven goal to run the Sonar plugin. (default: sonar:sonar)
 197     :stream: Keyword used to represent a release code-name.
 198         Often the same as the branch. (default: master)
 199     :submodule-recursive: Whether to checkout submodules recursively.
 200         (default: true)
 201     :submodule-timeout: Timeout (in minutes) for checkout operation.
 202         (default: 10)
 203     :submodule-disable: Disable submodule checkout operation.
 204         (default: false)
 205     :tox-dir: Directory containing the project's tox.ini relative to
 206         the workspace. The default uses tox.ini at the project root.
 207         (default: '.')
 208     :tox-envs: Tox environments to run. If blank run everything described
 209         in tox.ini. (default: '')
 210     :gerrit_sonar_triggers: Override Gerrit Triggers.
 211     :gerrit_trigger_file_paths: Override file paths used to filter which file
 212         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 213         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 214
 215 .. comment Stop ignoring
 216
 217
 218 Tox SonarQube
 219 -------------
 220
 221 The SonarQube job invokes tox to run tests and generate code-coverage
 222 statistics, then runs the SonarQube Scanner Jenkins plug-in to analyze
 223 code, gather coverage data, and upload the results to a SonarQube server
 224 such as SonarCloud.io. Optionally runs a shell script before tox.
 225
 226 Requires ``SonarQube Scanner for Jenkins``
 227
 228 This job runs on the master branch because the basic Sonar configuration
 229 does not support multi-branch.
 230
 231 Plug-in configurations
 232     Manage Jenkins --> Configure System --> SonarQube servers
 233         - Name: Sonar (fixed)
 234         - Server URL: https://sonar.project.org/ or https://sonarcloud.io
 235         - Server authentication token: none for local, API token (saved as
 236           a "secret text" credential) for Sonarcloud
 237
 238     Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
 239         - Name: SonarQube Scanner (fixed)
 240         - Install automatically
 241         - Select latest version
 242
 243 :Template Names:
 244
 245     - {project-name}-tox-sonarqube
 246     - gerrit-tox-sonarqube
 247     - github-tox-sonarqube
 248
 249 :Comment Trigger: ``run-sonar``
 250
 251 :Required parameters:
 252
 253     :build-node: The node to run the build on.
 254         (Commonly in defaults.yaml)
 255     :jenkins-ssh-credential: Credential to use for SSH.
 256         (Commonly in defaults.yaml)
 257     :project: The git repository name.
 258     :project-name: Prefix used to name jobs.
 259
 260 .. comment Start ignoring WriteGoodLintBear
 261
 262 :Optional Parameters:
 263
 264     :archive-artifacts: Pattern for files to archive to the logs server
 265         (default: '\*\*/\*.log')
 266     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 267     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 268     :cron: Cron schedule when to trigger the job. This parameter also
 269         supports multiline input via YAML pipe | character in cases where
 270         one may want to provide more than 1 cron timer.  (default: @weekly)
 271     :disable-job: Whether to disable the job (default: false)
 272     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 273     :github-url: URL for Github. (default: https://github.com)
 274     :parallel: Boolean indicator for tox to run tests in parallel or series.
 275         (default: false, in series)
 276     :pre-build-script: Shell script to run before tox. Useful for setting up
 277         dependencies. (default: a string with a shell comment)
 278     :python-version: Python version to invoke pip install of tox-pyenv
 279         (default: python3)
 280     :sonar-additional-args: Command line arguments. (default: '')
 281     :sonar-java-opts: JVM options. For example, use option -Xmx
 282         to increase the memory size limit.  (default: '')
 283     :sonar-project-file: The file name with Sonar configuration properties
 284         (default: sonar-project.properties)
 285     :sonar-properties: Sonar configuration properties. (default: '')
 286     :sonar-task: Sonar task to run. (default: '')
 287     :tox-dir: Directory containing the project's tox.ini relative to
 288         the workspace. The default uses tox.ini at the project root.
 289         (default: '.')
 290     :tox-envs: Tox environments to run. If blank run everything described
 291         in tox.ini. (default: '')
 292
 293 .. comment Stop ignoring
 294
 295 .. note:: A job definition must provide one of the optional parameters
 296     ``sonar-project-file`` and ``sonar-properties``; they cannot both be
 297     empty.  Set Sonar properties directly in the job definition by setting
 298     the ``sonar-project-file`` property to ``""`` and adding all properties
 299     under ``sonar-properties``.
 300
 301 :Required Sonar Properties:
 302
 303     - sonar.login: The API token for authentication at SonarCloud.
 304       Commonly defined as key "sonarcloud_api_token" in defaults.yaml.
 305     - sonar.organization: The umbrella project name; e.g., "opendaylight".
 306       Commonly defined as key "sonarcloud_project_organization" in defaults.yaml.
 307     - sonar.projectName: The git repository name without slashes; e.g., "infrautils".
 308     - sonar.projectKey: The globally unique key for the report in SonarCloud. Most
 309       teams use the catenation of sonar.organization, an underscore, and
 310       sonar.projectName; e.g., "opendaylight_infrautils".
 311
 312 :Optional Sonar Properties:
 313
 314     - sonar.cfamily.gcov.reportsPath: directory with GCOV output files
 315     - Documentation of SonarQube properties is here:
 316       https://docs.sonarqube.org/latest/analysis/overview/
 317
 318
 319 Example job definition
 320 ^^^^^^^^^^^^^^^^^^^^^^
 321
 322 The following example defines a job for a basic Python project. This definition
 323 uses configuration parameters in the umbrella project's defaults.yaml file.
 324
 325 .. code-block:: yaml
 326
 327     - project:
 328         name: my-package-sonar
 329         project: my/package
 330         project-name: my-package
 331         sonar-project-file: ""
 332         sonar-properties: |
 333             sonar.login={sonarcloud_api_token}
 334             sonar.projectKey={sonarcloud_project_organization}_{project-name}
 335             sonar.projectName={project-name}
 336             sonar.organization={sonarcloud_project_organization}
 337             sonar.sourceEncoding=UTF-8
 338             sonar.sources=mypackage
 339             sonar.exclusions=tests/*,setup.py
 340             sonar.python.coverage.reportPaths=coverage.xml
 341         jobs:
 342           - gerrit-tox-sonarqube
 343
 344
 345 Tox Verify
 346 ----------
 347
 348 Tox runner to verify a project on creation of a patch set.  This job
 349 is pyenv aware so if the image contains an installation of pyenv at
 350 /opt/pyenv it will pick it up and run Python tests with the
 351 appropriate Python versions. This job will set the following pyenv
 352 variables before running.
 353
 354 .. code:: bash
 355
 356    export PYENV_ROOT="/opt/pyenv"
 357    export PATH="$PYENV_ROOT/bin:$PATH"
 358
 359 :Template Names:
 360
 361     - {project-name}-tox-verify-{stream}
 362     - gerrit-tox-verify
 363     - github-tox-verify
 364
 365 :Comment Trigger: **recheck|reverify** post a comment with one of the
 366     triggers to launch this job manually. Do not include any other
 367     text or vote in the same comment.
 368
 369 :Required Parameters:
 370
 371     :build-node: The node to run build on.
 372     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 373         in defaults.yaml)
 374
 375 :Optional Parameters:
 376
 377     :branch: The branch to build against. (default: master)
 378     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 379     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 380     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 381     :pre-build-script: Shell script to execute before the Tox builder.
 382         For example, install prerequisites or move files to the repo root.
 383         (default: a string with a shell comment)
 384     :parallel: Boolean indicator for tox to run tests in parallel or series.
 385        (default: false, in series)
 386     :python-version: Python version to invoke pip install of tox-pyenv
 387         (default: python2)
 388     :stream: Keyword representing a release code-name.
 389         Often the same as the branch. (default: master)
 390     :submodule-recursive: Whether to checkout submodules recursively.
 391         (default: true)
 392     :submodule-timeout: Timeout (in minutes) for checkout operation.
 393         (default: 10)
 394     :submodule-disable: Disable submodule checkout operation.
 395         (default: false)
 396     :tox-dir: Directory containing the project's tox.ini relative to
 397         the workspace. The default uses tox.ini at the project root.
 398         (default: '.')
 399     :tox-envs: Tox environments to run. If blank run everything described
 400         in tox.ini. (default: '')
 401     :gerrit_trigger_file_paths: Override file paths used to filter which file
 402         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 403         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 404
 405
 406 Tox Merge
 407 ---------
 408
 409 Tox runner to verify a project after merge of a patch set.  This job
 410 is pyenv aware so if the image contains an installation of pyenv at
 411 /opt/pyenv it will pick it up and run Python tests with the
 412 appropriate Python versions. This job will set the following pyenv
 413 variables before running.
 414
 415 .. code:: bash
 416
 417    export PYENV_ROOT="/opt/pyenv"
 418    export PATH="$PYENV_ROOT/bin:$PATH"
 419
 420 :Template Names:
 421
 422     - {project-name}-tox-merge-{stream}
 423     - gerrit-tox-merge
 424     - github-tox-merge
 425
 426 :Comment Trigger: **remerge** post a comment with the trigger to launch
 427     this job manually. Do not include any other text or vote in the
 428     same comment.
 429
 430 :Required Parameters:
 431
 432     :build-node: The node to run build on.
 433     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 434         in defaults.yaml)
 435
 436 :Optional Parameters:
 437
 438     :branch: The branch to build against. (default: master)
 439     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 440     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 441     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 442     :pre-build-script: Shell script to execute before the CLM builder.
 443         For example, install prerequisites or move files to the repo root.
 444         (default: a string with a shell comment)
 445     :python-version: Python version to invoke pip install of tox-pyenv
 446         (default: python2)
 447     :stream: Keyword representing a release code-name.
 448         Often the same as the branch. (default: master)
 449     :submodule-recursive: Whether to checkout submodules recursively.
 450         (default: true)
 451     :submodule-timeout: Timeout (in minutes) for checkout operation.
 452         (default: 10)
 453     :submodule-disable: Disable submodule checkout operation.
 454         (default: false)
 455     :tox-dir: Directory containing the project's tox.ini relative to
 456         the workspace. The default uses tox.ini at the project root.
 457         (default: '.')
 458     :tox-envs: Tox environments to run. If blank run everything described
 459         in tox.ini. (default: '')
 460     :gerrit_trigger_file_paths: Override file paths used to filter which file
 461         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 462         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 463
 464
 465 PyPI Merge
 466 ----------
 467
 468 Creates and uploads package distribution files on merge of a patch set.
 469 Runs tox, builds a source distribution and (optionally) a binary
 470 distribution, and uploads the distribution(s) to a PyPI repository.
 471 The project git repository must have a setup.py file
 472 with configuration for packaging the component.
 473
 474 Projects can choose **either** this template to publish on merge,
 475 **or** the Stage template to publish on command.
 476
 477 This job should use a staging repository like testpypi.python.org,
 478 which sets up use of release jobs to promote the distributions later.
 479 This job can also use a public release area like the global PyPI
 480 repository if the release process is not needed. These PyPI
 481 repositories allow upload of a package at a specific version once,
 482 they do not allow overwrite of a package.  This means that a merge job
 483 will fail in the upload step if the package version already exists in
 484 the target repository.
 485
 486 The tox runner is pyenv aware so if the image contains an installation
 487 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 488 the appropriate Python versions. The tox runner sets the following
 489 pyenv variables before running.
 490
 491 .. code:: bash
 492
 493    export PYENV_ROOT="/opt/pyenv"
 494    export PATH="$PYENV_ROOT/bin:$PATH"
 495
 496 See the recommended directory layout documented in the PyPI Verify job.
 497
 498 Jobs using this PyPI template depend on a .pypirc configuration file
 499 in the Jenkins builder home directory. An example appears next that uses
 500 API tokens. Note that in the [pypi] entry the repository key-value pair
 501 is optional, it defaults to pypi.org.
 502
 503 .. code-block:: bash
 504
 505     [distutils] # this tells distutils what package indexes you can push to
 506     index-servers = pypi-test pypi
 507
 508     [pypi-test]
 509     repository: https://test.pypi.org/legacy/
 510     username: __token__
 511     password: pypi-test-api-token-goes-here
 512
 513     [pypi]
 514     username: __token__
 515     password: pypi-api-token-goes-here
 516
 517
 518 :Template Names:
 519
 520     - {project-name}-pypi-merge-{stream}
 521     - gerrit-pypi-merge
 522     - github-pypi-merge
 523
 524 :Comment Trigger: **remerge** post a comment with the trigger to launch
 525     this job manually. Do not include any other text or vote in the
 526     same comment.
 527
 528 :Required Parameters:
 529
 530     :build-node: The node to run the build on.
 531     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 532         in defaults.yaml)
 533     :mvn-settings: The settings file with credentials for the project
 534     :project: Git repository name
 535     :project-name: Jenkins job name prefix
 536
 537 :Optional Parameters:
 538
 539     :branch: The branch to build against. (default: master)
 540     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 541     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 542     :cron: Cron schedule when to trigger the job. Supports regular builds.
 543         Not useful when publishing to pypi.org because that rejects a package
 544         if the version exists. (default: empty)
 545     :disable-job: Whether to disable the job (default: false)
 546     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 547     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 548     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 549     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 550     :mvn-version: Version of maven to use. (default: mvn35)
 551     :parallel: Boolean indicator for tox to run tests in parallel or series.
 552        (default: false, in series)
 553     :pre-build-script: Shell script to execute before the tox builder. For
 554         example, install system prerequisites. (default: a shell comment)
 555     :pypi-repo: Key for the PyPI target repository in the .pypirc file,
 556         ideally a server like test.pypi.org. (default: pypi-test)
 557     :python-version: Python version to invoke pip install of tox-pyenv
 558         (default: python3)
 559     :stream: Keyword representing a release code-name.
 560         Often the same as the branch. (default: master)
 561     :submodule-recursive: Whether to checkout submodules recursively.
 562         (default: true)
 563     :submodule-timeout: Timeout (in minutes) for checkout operation.
 564         (default: 10)
 565     :submodule-disable: Disable submodule checkout operation.
 566         (default: false)
 567     :tox-dir: Directory containing the project's tox.ini relative to
 568         the workspace. The default uses tox.ini at the project root.
 569         (default: '.')
 570     :tox-envs: Tox environments to run. If blank run everything described
 571         in tox.ini. (default: '')
 572     :gerrit_trigger_file_paths: Override file paths used to filter which file
 573         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 574         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 575
 576
 577 PyPI Stage
 578 ----------
 579
 580 Creates and uploads package distribution files on receipt of a comment.
 581 Runs tox, builds a source distribution and (optionally) a binary
 582 distribution, and uploads the distribution(s) to a PyPI repository.
 583 The project git repository must have a setup.py file with configuration
 584 for packaging the component.
 585
 586 Projects can choose **either** this template to publish on command,
 587 **or** the Merge template to publish on merge.
 588
 589 This job should use a staging repository like testpypi.python.org,
 590 which sets up use of release jobs to promote the distributions later.
 591 This job can also use a public release area like the global PyPI
 592 repository if the release process is not needed. These PyPI
 593 repositories allow upload of a package at a specific version once,
 594 they do not allow overwrite of a package.  This means that a job
 595 will fail in the upload step if the package version already exists in
 596 the target repository.
 597
 598 The tox runner is pyenv aware so if the image contains an installation
 599 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 600 the appropriate Python versions. The tox runner sets the following
 601 pyenv variables before running.
 602
 603 .. code:: bash
 604
 605    export PYENV_ROOT="/opt/pyenv"
 606    export PATH="$PYENV_ROOT/bin:$PATH"
 607
 608 See the recommended directory layout documented in the PyPI Verify job.
 609
 610 Jobs using this PyPI template depend on a .pypirc configuration file
 611 in the Jenkins builder home directory. An example appears next that uses
 612 API tokens. Note that in the [pypi] entry the repository key-value pair
 613 is optional, it defaults to pypi.org.
 614
 615 .. code-block:: bash
 616
 617     [distutils] # this tells distutils what package indexes you can push to
 618     index-servers = pypi-test pypi
 619
 620     [pypi-test]
 621     repository: https://test.pypi.org/legacy/
 622     username: __token__
 623     password: pypi-test-api-token-goes-here
 624
 625     [pypi]
 626     username: __token__
 627     password: pypi-api-token-goes-here
 628
 629
 630 :Template Names:
 631
 632     - {project-name}-pypi-stage-{stream}
 633     - gerrit-pypi-stage
 634     - github-pypi-stage
 635
 636 :Comment Trigger: **stage-release** post a comment with the trigger to launch
 637     this job manually. Do not include any other text or vote in the
 638     same comment.
 639
 640 :Required Parameters:
 641
 642     :build-node: The node to run the build on.
 643     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 644         in defaults.yaml)
 645     :mvn-settings: The settings file with credentials for the project
 646     :project: Git repository name
 647     :project-name: Jenkins job name prefix
 648
 649 :Optional Parameters:
 650
 651     :branch: The branch to build against. (default: master)
 652     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 653     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 654     :cron: Cron schedule when to trigger the job. Supports regular builds.
 655         Not useful when publishing to pypi.org because that rejects a package
 656         if the version exists. (default: empty)
 657     :disable-job: Whether to disable the job (default: false)
 658     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 659     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 660     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 661     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 662     :mvn-version: Version of maven to use. (default: mvn35)
 663     :parallel: Boolean indicator for tox to run tests in parallel or series.
 664        (default: false, in series)
 665     :pre-build-script: Shell script to execute before the tox builder. For
 666         example, install system prerequisites. (default: a shell comment)
 667     :pypi-repo: Key for the PyPI target repository in the .pypirc file,
 668         ideally a server like test.pypi.org. (default: pypi-test)
 669     :python-version: Python version to invoke pip install of tox-pyenv
 670         (default: python3)
 671     :stream: Keyword representing a release code-name.
 672         Often the same as the branch. (default: master)
 673     :submodule-recursive: Whether to checkout submodules recursively.
 674         (default: true)
 675     :submodule-timeout: Timeout (in minutes) for checkout operation.
 676         (default: 10)
 677     :submodule-disable: Disable submodule checkout operation.
 678         (default: false)
 679     :tox-dir: Directory containing the project's tox.ini relative to
 680         the workspace. The default uses tox.ini at the project root.
 681         (default: '.')
 682     :tox-envs: Tox environments to run. If blank run everything described
 683         in tox.ini. (default: '')
 684     :gerrit_trigger_file_paths: Override file paths used to filter which file
 685         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 686         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 687
 688 PyPI Verify
 689 -----------
 690
 691 Verifies a Python library project on creation of a patch set. Runs tox
 692 then builds a source distribution and (optionally) a binary
 693 distribution. The project repository must have a setup.py file with
 694 configuration for packaging the component.
 695
 696 Installable package projects should use the directory layout shown
 697 below. All Python files are in a repo subdirectory separate from
 698 non-Python files like documentation. This layout allows highly
 699 specific build-job triggers in Jenkins using the subdirectory
 700 paths. For example, a PyPI publisher job should not run on a non-Python
 701 file change such as documentation, because the job cannot upload the
 702 same package twice.
 703
 704 To make the document files available for building a Python package
 705 long description in setup.py, add a symbolic link "docs" in the
 706 package subdirectory pointing to the top-level docs directory.
 707
 708 .. code-block:: bash
 709
 710     git-repo-name/
 711     │
 712     ├── docs/
 713     │   ├── index.rst
 714     │   └── release-notes.rst
 715     │
 716     ├── helloworld-package/
 717     │   │
 718     │   └── helloworld/
 719     │   │   ├── __init__.py
 720     │   │   ├── helloworld.py
 721     │   │   └── helpers.py
 722     │   │
 723     │   ├── tests/
 724     │   │   ├── helloworld_tests.py
 725     │   │   └── helloworld_mocks.py
 726     │   │
 727     │   ├── requirements.txt
 728     │   └── setup.py
 729     │   └── tox.ini
 730     │
 731     ├── releases/
 732     │   └── pypi-helloworld.yaml
 733     │
 734     ├── .gitignore
 735     ├── LICENSE
 736     └── README.md
 737
 738
 739 The tox runner is pyenv aware so if the image contains an installation
 740 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 741 the appropriate Python versions. The tox runner sets the following
 742 pyenv variables before running.
 743
 744 .. code:: bash
 745
 746    export PYENV_ROOT="/opt/pyenv"
 747    export PATH="$PYENV_ROOT/bin:$PATH"
 748
 749 :Template Names:
 750
 751     - {project-name}-pypi-verify-{stream}
 752     - gerrit-pypi-verify
 753     - github-pypi-verify
 754
 755 :Comment Trigger: **recheck|reverify** post a comment with one of the
 756     triggers to launch this job manually. Do not include any other
 757     text or vote in the same comment.
 758
 759 :Required Parameters:
 760
 761     :build-node: The node to run the build on.
 762     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 763         in defaults.yaml)
 764     :mvn-settings: The settings file with credentials for the project
 765     :project: Git repository name
 766     :project-name: Jenkins job name prefix
 767
 768 :Optional Parameters:
 769
 770     :branch: The branch to build against. (default: master)
 771     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 772     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 773     :disable-job: Whether to disable the job (default: false)
 774     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 775     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 776     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 777     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 778     :mvn-version: Version of maven to use. (default: mvn35)
 779     :parallel: Boolean indicator for tox to run tests in parallel or series.
 780        (default: false, in series)
 781     :pre-build-script: Shell script to execute before the tox builder. For
 782         example, install system prerequisites. (default: a shell comment)
 783     :python-version: Python version to invoke pip install of tox-pyenv
 784         (default: python3)
 785     :stream: Keyword representing a release code-name.
 786         Often the same as the branch. (default: master)
 787     :submodule-recursive: Whether to checkout submodules recursively.
 788         (default: true)
 789     :submodule-timeout: Timeout (in minutes) for checkout operation.
 790         (default: 10)
 791     :submodule-disable: Disable submodule checkout operation.
 792         (default: false)
 793     :tox-dir: Directory containing the project's tox.ini relative to
 794         the workspace. The default uses tox.ini at the project root.
 795         (default: '.')
 796     :tox-envs: Tox environments to run. If blank run everything described
 797         in tox.ini. (default: '')
 798     :gerrit_trigger_file_paths: Override file paths used to filter which file
 799         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 800         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit