Fix: Request Python 3 -> 3.8

[releng/global-jjb.git] / docs / jjb / lf-release-jobs.rst

diff --git a/docs/jjb/lf-release-jobs.rst b/docs/jjb/lf-release-jobs.rst
index 2413190..f872808 100644 (file)
--- a/docs/jjb/lf-release-jobs.rst
+++ b/docs/jjb/lf-release-jobs.rst
@@ -50,6 +50,12 @@ For example, the parameters for a Maven release are as follows::
     USE_RELEASE_FILE = false
     DRY_RUN = false
 
     USE_RELEASE_FILE = false
     DRY_RUN = false
 

+It's recommended to use Semantic Versions (SemVer) for releases. Refer to
+https://semver.org for more details on SemVer. For projects that do not
+follow SemVer can use a build parameter (OVERRIDE_SEMVER_REGEX) with the
+release job. This build param overrides the default SemVer regex.
+
+

 Maven Release Files
 -------------------
 
 Maven Release Files
 -------------------
 


@@ -70,8 +76,8 @@ The following parameters must appear in a maven release yaml file.
 :Required Parameters:
 
     :distribution_type: Must be "maven".
 :Required Parameters:
 
     :distribution_type: Must be "maven".

-    :log_dir: The suffix of the logs URL reported on completion by the
-        Jenkins stage job that created and pushed the artifact
+    :log_dir: The suffix of the logs URL reported on successful completion
+        by the Jenkins stage job that created and pushed the artifact

         to the staging repository.  For example, use value
         "example-project-maven-stage-master/17" for the logs URL
         https://logs.lf-project.org/production/vex-sjc-lfp-jenkins-prod-1/example-project-maven-stage-master/17
         to the staging repository.  For example, use value
         "example-project-maven-stage-master/17" for the logs URL
         https://logs.lf-project.org/production/vex-sjc-lfp-jenkins-prod-1/example-project-maven-stage-master/17


@@ -82,6 +88,8 @@ The following parameters must appear in a maven release yaml file.
 
     :git_tag: The tag string to sign and push to the Git repository.
        (default: the semantic version string)
 
     :git_tag: The tag string to sign and push to the Git repository.
        (default: the semantic version string)

+    :tag_release: Tag Gerrit Repo during the release process.
+       (default: true)

 
 The JSON schema for a maven release file appears below.
 
 
 The JSON schema for a maven release file appears below.
 


@@ -132,6 +140,8 @@ The following parameters must appear in a container release yaml file.
 
     :git_tag: The tag string to sign and push to the Git repository.
        (default: the semantic version string)
 
     :git_tag: The tag string to sign and push to the Git repository.
        (default: the semantic version string)

+    :tag_release: Tag Gerrit Repo during the release process.
+       (default: true)

 
 The JSON schema for a container release file appears below.
 
 
 The JSON schema for a container release file appears below.
 


@@ -162,9 +172,9 @@ packages.
 
 :Required Parameters:
 
 
 :Required Parameters:
 

-    :log_dir: The suffix of the logs URL reported on completion by the
-        Jenkins merge job that created and pushed the distribution files
-        to the staging repository.  For example, use value
+    :log_dir: The suffix of the logs URL reported on successful completion
+        by the Jenkins merge job that created and pushed the distribution
+        files to the staging repository.  For example, use value

         "example-project-pypi-merge-master/17" for the logs URL
         https://logs.lf-project.org/production/vex-sjc-lfp-jenkins-prod-1/example-project-pypi-merge-master/17
     :pypi_project: The PyPI project name at the staging and
         "example-project-pypi-merge-master/17" for the logs URL
         https://logs.lf-project.org/production/vex-sjc-lfp-jenkins-prod-1/example-project-pypi-merge-master/17
     :pypi_project: The PyPI project name at the staging and


@@ -179,6 +189,8 @@ packages.
 
     :git_tag: The tag string to sign and push to the Git repository.
        (default: the semantic version string)
 
     :git_tag: The tag string to sign and push to the Git repository.
        (default: the semantic version string)

+    :tag_release: Tag Gerrit Repo during the release process.
+       (default: true)

 
 The JSON schema for a PyPI release file appears below.
 
 
 The JSON schema for a PyPI release file appears below.
 


@@ -196,9 +208,15 @@ must start with "packagecloud". For example releases/packagecloud-1.6-tree.yaml
 
     $ cat releases/packagecloud-1.6-tree.yaml
     ---
 
     $ cat releases/packagecloud-1.6-tree.yaml
     ---

-    package_name:
-        - name: tree-1.6.0-10.el7.x86_64.rpm
-        - name: test.rpm
+    package_name: tree
+    packages:
+        - name: tree_1.6.0_amd64.deb
+        - name: tree-dev_1.6.0_amd64.deb
+        - name: tree-devel-1.6.0-1.x86_64.rpm
+        - name: tree-1.6.0-1.x86_64.rpm
+    ref: 5555cd2dd345fbeec0d3e2162e00835852342cda
+    log_dir: example-project-packagecloud-merge/21
+    version: 1.6.0

 
 The following parameters must appear in the PackageCloud release yaml file.
 These are not part of the Jenkins job definition to allow independent
 
 The following parameters must appear in the PackageCloud release yaml file.
 These are not part of the Jenkins job definition to allow independent


@@ -207,13 +225,27 @@ packages.
 
 :Required Parameters:
 
 
 :Required Parameters:
 

-    :package_name: A list of names that specify the packages to promote.
-        (Found in jenkins console log when using gem to push package eg.
+    :package_name: Name of the release package.
+    :packages: A list of names that specify the packages to promote.
+        Found in jenkins console log when using gem to push package eg.

         "Pushing /path/of/package/name-of-package.rpm... success!"
         OR using rest api call to query packagecloud.io repo
         "curl https://packagecloud.io/api/v1/repos/test_user/test_repo/search?q=
         | yq -r .[].filename"
         "Pushing /path/of/package/name-of-package.rpm... success!"
         OR using rest api call to query packagecloud.io repo
         "curl https://packagecloud.io/api/v1/repos/test_user/test_repo/search?q=
         | yq -r .[].filename"

+    :ref: The git commit reference (SHA-1 code) to tag with the version string.
+    :log_dir: The suffix of the logs URL reported on successful completion
+        by the Jenkins merge job that created and pushed the distribution
+        files to the staging repository. For example, use value
+        "example-project-packagecloud-merge-/21" for the logs URL
+        https://logs.lf-project.org/production/vex-sjc-lfp-jenkins-prod-1/example-project-packagecloud-merge/21
+    :version: The semantic version string used for the package.

 
 

+:Optional Parameters:
+
+    :git_tag: The tag string to sign and push to the Git repository.
+       (default: the semantic version string)
+    :tag_release: Tag Gerrit Repo during the release process.
+       (default: true)

 
 The JSON schema for a PackageCloud release file appears below.
 
 
 The JSON schema for a PackageCloud release file appears below.
 


@@ -221,6 +253,15 @@ The JSON schema for a PackageCloud release file appears below.
    :language: yaml
 
 
    :language: yaml
 
 

+Job Groups
+==========
+
+Below is a list of Release job groups:
+
+.. literalinclude:: ../../jjb/lf-release-job-groups.yaml
+   :language: yaml
+
+

 Jenkins Jobs
 ------------
 
 Jenkins Jobs
 ------------
 


@@ -261,6 +302,10 @@ Release Merge
 
 This template supports Maven and Container release jobs.
 
 
 This template supports Maven and Container release jobs.
 

+This template uses a git commit choosing strategy that builds the merged
+commit with the release yaml file, not the tip of the target branch, so
+projects can repeat the release action in case of merge job failure.
+

 :Template Name: {project-name}-release-merge
 
 :Comment Trigger: remerge
 :Template Name: {project-name}-release-merge
 
 :Comment Trigger: remerge


@@ -280,11 +325,8 @@ This template supports Maven and Container release jobs.
 
     :gerrit_merge_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths filter which checks which
 
     :gerrit_merge_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths filter which checks which

-        file modifications will trigger a build.
-        **default**::
-
-            - compare-type: REG_EXP
-              pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'
+        file modifications will trigger a build. The default pattern is the
+        regular expression ``(releases\/.*\.yaml|\.releases\/.*\.yaml)``

 
 
 Release Verify
 
 
 Release Verify


@@ -314,11 +356,8 @@ This template supports Maven and Container release jobs.
 
     :gerrit_verify_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths filter which checks which
 
     :gerrit_verify_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths filter which checks which

-        file modifications will trigger a build.
-        **default**::
-
-            - compare-type: REG_EXP
-              pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'
+        file modifications will trigger a build. The default pattern is the
+        regular expression ``(releases\/.*\.yaml|\.releases\/.*\.yaml)``

 
 
 PyPI Release Merge
 
 
 PyPI Release Merge


@@ -331,6 +370,10 @@ artifacts to the PyPI release repository, tags the git repository,
 signs the tag and pushes the tag to the git server. The release merge
 template accepts neither a branch nor a stream parameter.
 
 signs the tag and pushes the tag to the git server. The release merge
 template accepts neither a branch nor a stream parameter.
 

+These templates use a git commit choosing strategy that builds the merged
+commit with the release yaml file, not the tip of the target branch, so
+projects can repeat the release action in case of merge job failure.
+

 :Template Names:
 
     - {project-name}-pypi-release-merge
 :Template Names:
 
     - {project-name}-pypi-release-merge


@@ -359,12 +402,9 @@ template accepts neither a branch nor a stream parameter.
         should be the repository pypy.org. (default: pypi)
     :use-release-file: Whether to use the release file. (default: true)
 
         should be the repository pypy.org. (default: pypi)
     :use-release-file: Whether to use the release file. (default: true)
 

-    :gerrit_trigger_file_paths: Override file paths filter which checks which
-        file modifications will trigger a build.
-        **default**::
-
-            - compare-type: REG_EXP
-              pattern: '(releases\/pypi.*\.yaml|\.releases\/pypi.*\.yaml)'
+    :gerrit_release_trigger_file_paths: Override file paths filter which checks
+        which file modifications will trigger a build. The default pattern is the
+        regular expression ``(releases\/pypi.*\.yaml|\.releases\/pypi.*\.yaml)``

 
 PyPI Release Verify
 ~~~~~~~~~~~~~~~~~~~
 
 PyPI Release Verify
 ~~~~~~~~~~~~~~~~~~~


@@ -403,17 +443,17 @@ verify template accepts neither a branch nor a stream parameter.
         should be the repository pypy.org (default: pypi)
     :use-release-file: Whether to use the release file. (default: true)
 
         should be the repository pypy.org (default: pypi)
     :use-release-file: Whether to use the release file. (default: true)
 

-    :gerrit_trigger_file_paths: Override file paths filter which checks which
-        file modifications will trigger a build.
-        **default**::
-
-            - compare-type: REG_EXP
-              pattern: '(releases\/pypi.*\.yaml|\.releases\/pypi.*\.yaml)'
+    :gerrit_release_trigger_file_paths: Override file paths filter which checks
+        which file modifications will trigger a build. The default pattern is the
+        regular expression ``(releases\/pypi.*\.yaml|\.releases\/pypi.*\.yaml)``

 
 PackageCloud Release Verify
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
 PackageCloud Release Verify
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

-This template supports PackageCloud release jobs.
+This template supports PackageCloud release jobs. Checks that the specified
+packages are present in the staging repository and absent from the release
+repository. The file path trigger uses the regular expression
+``(releases\/packagecloud.*\.yaml|\.releases\/packagecloud.*\.yaml)``

 
 :Template Name: {project-name}-packagecloud-release-verify
 
 
 :Template Name: {project-name}-packagecloud-release-verify
 


@@ -435,25 +475,23 @@ This template supports PackageCloud release jobs.
     :gerrit-skip-vote: Skip voting for this job. (default: false)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 
     :gerrit-skip-vote: Skip voting for this job. (default: false)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 

-    :gerrit_verify_triggers: Override Gerrit Triggers.
-    :gerrit_trigger_file_paths: Override file paths filter which checks which
-        file modifications will trigger a build.
-        **default**::
-
-            - compare-type: REG_EXP
-              pattern: '(releases\/packagecloud.*\.yaml|\.releases\/packagecloud.*\.yaml)'
-
-

 PackageCloud Release Merge
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 PackageCloud Release Merge
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

-This template supports PackageCloud release jobs.
+This template supports PackageCloud release jobs.  Promotes the specified
+packages from the staging repository to the release repository.
+The file path trigger uses the regular expression
+``(releases\/packagecloud.*\.yaml|\.releases\/packagecloud.*\.yaml)``
+
+This template uses a git commit choosing strategy that builds the merged
+commit with the release yaml file, not the tip of the target branch, so
+projects can repeat the release action in case of merge job failure.

 
 

-:template name: {project-name}-packagecloud-release-merge
+:Template Name: {project-name}-packagecloud-release-merge

 
 

-:comment trigger: remerge
+:Comment Trigger: remerge

 
 

-:required parameters:
+:Required Parameters:

 
     :build-node: the node to run build on.
     :jenkins-ssh-release-credential: credential to use for ssh. (generally set
 
     :build-node: the node to run build on.
     :jenkins-ssh-release-credential: credential to use for ssh. (generally set


@@ -461,20 +499,11 @@ This template supports PackageCloud release jobs.
     :project: git repository name
     :project-name: jenkins job name prefix
 
     :project: git repository name
     :project-name: jenkins job name prefix
 

-:optional parameters:
+:Optional Parameters:

 
     :build-days-to-keep: days to keep build logs in jenkins. (default: 7)
     :build-timeout: timeout in minutes before aborting build. (default: 15)
 
 
     :build-days-to-keep: days to keep build logs in jenkins. (default: 7)
     :build-timeout: timeout in minutes before aborting build. (default: 15)
 

-    :gerrit_merge_triggers: override gerrit triggers.
-    :gerrit_trigger_file_paths: override file paths filter which checks which
-        file modifications will trigger a build.
-        **default**::
-
-            - compare-type: reg_exp
-              pattern: '(releases\/packagecloud.*\.yaml|\.releases\/packagecloud.*\.yaml)'
-
-

 Setup for LFID, Nexus, Jenkins and Gerrit
 -----------------------------------------
 
 Setup for LFID, Nexus, Jenkins and Gerrit
 -----------------------------------------