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