X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=blobdiff_plain;f=docs%2Fjjb%2Flf-python-jobs.rst;h=8f4f6bde50b5c08246d9131229a30acff9bddf9a;hb=8f45c24bd2d164ef934d68982662e045fcb0dcb2;hp=bea44fc43b8f078e421a65b28ada5c72f646cdcd;hpb=3dd1773c0ec86b6f24f5e31df7ea0d8650c3c092;p=releng%2Fglobal-jjb.git

diff --git a/docs/jjb/lf-python-jobs.rst b/docs/jjb/lf-python-jobs.rst
index bea44fc4..8f4f6bde 100644
--- a/docs/jjb/lf-python-jobs.rst
+++ b/docs/jjb/lf-python-jobs.rst
@@ -29,9 +29,10 @@ lf-infra-pypi-tag-release
 -------------------------
 
 Checks the format of the release version string and checks the git
-repository for that tag. In a merge job, continues to tag the repository
-and push the tag to the git server. Also installs supporting tools
-including Sigul and lftools.  Sigul requires a CentOS build node.
+repository for that tag. In a merge job, if the tag does not exist,
+adds the tag to the repository, signs the tag, and pushes the tag
+to the git server. Signing requires sigul, which is only available
+on a CentOS build node.
 
 lf-infra-pypi-upload
 --------------------
@@ -43,7 +44,7 @@ Jenkins server must have a configuration file ".pypirc".
 :Required Parameters:
 
     :pypi-repo: PyPI repository key in .pypirc configuration file;
-        e.g., "staging" or "pypi".
+        e.g., "pypi-test" or "pypi".
 
 lf-infra-tox-install
 --------------------
@@ -127,7 +128,7 @@ Python Sonar with Tox
 
 Sonar scans for Python based repos. This job invokes tox to run tests
 and gather coverage statistics from the test results, then invokes
-Maven to publish the results to a Sonar server.
+Maven to publish the results to either a Sonar server or SonarCloud.
 
 To get the Sonar coverage results, file tox.ini must exist and contain
 coverage commands to run.
@@ -136,8 +137,8 @@ The coverage commands define the code that gets executed by the test
 suites.  Checking coverage does not guarantee that the tests execute
 properly, but it identifies code that is not executed by any test.
 
-This job reuses the Sonar builder used in Java/Maven projects which
-runs maven twice. The first invocation does nothing for Python
+This job reuses the Sonar builders used for Java/Maven projects which
+run maven twice. The first invocation does nothing for Python
 projects, so the job uses the goal 'validate' by default. The second
 invocation publishes results using the goal 'sonar:sonar' by default.
 
@@ -195,6 +196,12 @@ https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
         (default: a string with a shell comment)
     :python-version: Python version to invoke pip install of tox-pyenv
         (default: python2)
+    :sonarcloud: Whether or not to use SonarCloud ``true|false``.
+        (default: false)
+    :sonarcloud-project-key: SonarCloud project key. (default: '')
+    :sonarcloud-project-organization: SonarCloud project organization.
+        (default: '')
+    :sonarcloud-api-token: SonarCloud API Token. (default: '')
     :sonar-mvn-goal: The Maven goal to run the Sonar plugin. (default: sonar:sonar)
     :stream: Keyword used to represent a release code-name.
         Often the same as the branch. (default: master)
@@ -204,6 +211,11 @@ https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
         (default: 10)
     :submodule-disable: Disable submodule checkout operation.
         (default: false)
+    :tox-dir: Directory containing the project's tox.ini relative to
+        the workspace. The default uses tox.ini at the project root.
+        (default: '.')
+    :tox-envs: Tox environments to run. If blank run everything described
+        in tox.ini. (default: '')
     :gerrit_sonar_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths used to filter which file
         modifications trigger a build. Refer to JJB documentation for "file-path" details.
@@ -331,7 +343,7 @@ PyPI Verify
 
 Verifies a Python library project on creation of a patch set. Runs tox
 then builds a source distribution and (optionally) a binary
-distribution.  The project repository must have a setup.py file with
+distribution. The project repository must have a setup.py file with
 configuration for packaging the component.
 
 The tox runner is pyenv aware so if the image contains an installation
@@ -363,6 +375,7 @@ pyenv variables before running.
     :branch: The branch to build against. (default: master)
     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
     :build-timeout: Timeout in minutes before aborting build. (default: 15)
+    :disable-job: Whether to disable the job (default: false)
     :dist-binary: Whether to build a binary wheel distribution. (default: true)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
     :parallel: Boolean indicator for tox to run tests in parallel or series.
@@ -392,10 +405,10 @@ pyenv variables before running.
 PyPI Merge
 ----------
 
-Creates and uploads distribution files on merge of a patch set.  Runs
+Creates and uploads distribution files on merge of a patch set. Runs
 tox, builds a source distribution and (optionally) a binary
 distribution, and uploads the distribution(s) to a PyPI repository.
-This job should be configured to use a staging PyPI repository like
+This job should be configured to use a test PyPI repository like
 testpypi.python.org, not a public release area like the global PyPI
 repository. Like the verify job, this requires a setup.py file for
 packaging the component.
@@ -411,25 +424,23 @@ pyenv variables before running.
    export PATH="$PYENV_ROOT/bin:$PATH"
 
 
-Requires a .pypirc configuration file in the Jenkins builder home
-directory, an example appears next.
+Requires a .pypirc configuration file in the Jenkins builder home directory,
+an example appears next that uses API tokens. No repository is needed in the
+PyPI section.
 
 .. code-block:: bash
 
     [distutils] # this tells distutils what package indexes you can push to
-    index-servers =
-    staging
-    pypi
+    index-servers = pypi-test pypi
 
-    [staging]
-    repository: https://testpypi.python.org/pypi
-    username: your_username
-    password: your_password
+    [pypi-test]
+    repository: https://test.pypi.org/legacy/
+    username: __token__
+    password: pypi-test-api-token-goes-here
 
     [pypi]
-    repository: https://pypi.python.org/pypi
-    username: your_username
-    password: your_password
+    username: __token__
+    password: pypi-api-token-goes-here
 
 
 :Template Names:
@@ -438,7 +449,7 @@ directory, an example appears next.
     - gerrit-pypi-merge
     - github-pypi-merge
 
-:Comment Trigger: pypi-remerge
+:Comment Trigger: remerge
 
 :Required Parameters:
 
@@ -451,6 +462,10 @@ directory, an example appears next.
     :branch: The branch to build against. (default: master)
     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
     :build-timeout: Timeout in minutes before aborting build. (default: 15)
+    :cron: Cron schedule when to trigger the job. Supports daily builds.
+        This parameter also supports multiline input via YAML pipe | character in
+        cases where one may want to provide more than 1 cron timer. (default: empty)
+    :disable-job: Whether to disable the job (default: false)
     :dist-binary: Whether to build a binary wheel distribution. (default: true)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
     :parallel: Boolean indicator for tox to run tests in parallel or series.
@@ -458,7 +473,7 @@ directory, an example appears next.
     :pre-build-script: Shell script to execute before the tox builder. For
         example, install system prerequisites. (default: a shell comment)
     :pypi-repo: Key for PyPI repository parameters in the .pypirc file.
-        Merge jobs should use a server like testpypi.python.org.  (default: staging)
+        Merge jobs should use a server like testpypi.python.org. (default: pypi-test)
     :python-version: Python version to invoke pip install of tox-pyenv
         (default: python3)
     :stream: Keyword representing a release code-name.
@@ -486,13 +501,13 @@ Verifies a Python library project on creation of a patch set with a
 release yaml file. Runs tox, builds source and (optionally) binary
 distributions, checks the format of the version string, checks that
 the distribution file names contain the release version string, and
-checks that no tag exists in the code repository for the release
+checks if the tag exists in the code repository for the release
 version.
 
 To initiate the release process, create a releases/ or .releases/
 directory at the root of the project repository, add one release yaml
 file to it, and submit a change set with that release yaml file. A
-schema and and an example for the release yaml file appear below.  The
+schema and and an example for the release yaml file appear below. The
 version in the release yaml file must be a valid Semantic Versioning
 (SemVer) string, matching either the pattern "v#.#.#" or "#.#.#" where
 "#" is one or more digits.
@@ -548,6 +563,8 @@ An example of a pypi release file appears below.
     - gerrit-pypi-release-verify
     - github-pypi-release-verify
 
+:Comment Trigger: recheck
+
 :Required Parameters:
 
     :build-node: The node to run build on, which must be Centos.
@@ -559,6 +576,7 @@ An example of a pypi release file appears below.
     :branch: The branch to build against. (default: master)
     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
     :build-timeout: Timeout in minutes before aborting build. (default: 15)
+    :disable-job: Whether to disable the job (default: false)
     :dist-binary: Whether to build a binary wheel distribution. (default: true)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
     :parallel: Boolean indicator for tox to run tests in parallel or series.
@@ -567,7 +585,7 @@ An example of a pypi release file appears below.
         For example, install prerequisites or move files to the repo root.
         (default: a string with a shell comment)
     :pypi-repo: Key for PyPI repository parameters in the .pypirc file.
-        Release jobs should use a server like pypy.org.  (default: pypi)
+        Release jobs should use a server like pypy.org. (default: pypi)
     :python-version: Python version to invoke pip install of tox-pyenv
         (default: python3)
     :stream: Keyword representing a release code-name.
@@ -584,25 +602,22 @@ An example of a pypi release file appears below.
     :tox-envs: Tox environments to run. If blank run everything described
         in tox.ini. (default: '')
     :use-release-file: Whether to use the release file. (default: true)
-    :gerrit_trigger_file_paths: Override file paths used to filter which file
-        modifications trigger a build. Refer to JJB documentation for "file-path" details.
-        https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
-
 
 PyPI Release Merge
 ------------------
 
 Publishes a Python library on merge of a patch set with a release yaml
-file.  Runs tox, builds source and (optionally) binary distributions,
+file. Runs tox, builds source and (optionally) binary distributions,
 checks the format of the version string, checks that the distribution
-file names contain the release version string, checks that no tag
-exists in the code repository for the release version, tags the code
-repository with the release version, pushes the tag to the git server,
-and uploads distributions to a PyPI repository.
+file names contain the release version string, checks if the tag
+exists in the code repository for the release version, then if the tag
+does not exist, tags the code repository with the release version,
+signs the tag and pushes the tag to the git server. Finally this
+uploads the distributions to a PyPI repository.
 
 This job is similar to the PyPI merge job, but is only triggered by
-merge of a release yaml file and checks the version and tag before
-uploading to a public repository such as PyPI.
+merge of a release yaml file, also this checks the version and tag
+before uploading to a public repository such as PyPI.
 
 See the PyPI Release Verify job above for documentation of the release
 yaml file format.
@@ -631,6 +646,8 @@ The special parameters are as follows::
     - gerrit-pypi-release-merge
     - github-pypi-release-merge
 
+:Comment Trigger: remerge
+
 :Required Parameters:
 
     :build-node: The node to run build on, which must be Centos.
@@ -642,6 +659,7 @@ The special parameters are as follows::
     :branch: The branch to build against. (default: master)
     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
     :build-timeout: Timeout in minutes before aborting build. (default: 15)
+    :disable-job: Whether to disable the job (default: false)
     :dist-binary: Whether to build a binary wheel distribution. (default: true)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
     :parallel: Boolean indicator for tox to run tests in parallel or series.
@@ -650,7 +668,7 @@ The special parameters are as follows::
         For example, install prerequisites or move files to the repo root.
         (default: a string with a shell comment)
     :pypi-repo: Key for PyPI repository parameters in the .pypirc file.
-        Release jobs should use a server like pypy.org.  (default: pypi)
+        Release jobs should use a server like pypy.org. (default: pypi)
     :python-version: Python version to invoke pip install of tox-pyenv
         (default: python3)
     :stream: Keyword representing a release code-name.
@@ -667,6 +685,3 @@ The special parameters are as follows::
     :tox-envs: Tox environments to run. If blank run everything described
         in tox.ini. (default: '')
     :use-release-file: Whether to use the release file. (default: true)
-    :gerrit_trigger_file_paths: Override file paths used to filter which file
-        modifications trigger a build. Refer to JJB documentation for "file-path" details.
-        https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit