Python merge use git choosing strategy default

[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..2ddc6ee 100644 (file)
--- a/docs/jjb/lf-release-jobs.rst
+++ b/docs/jjb/lf-release-jobs.rst
@@ -196,9 +196,15 @@ must start with "packagecloud". For example 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
@@ -207,13 +213,25 @@ packages.
 
 :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"
+    :ref: The git commit reference (SHA-1 code) to tag with the version string.
+    :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
+        "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)
 
 The JSON schema for a PackageCloud release file appears below.
 
@@ -261,6 +279,10 @@ Release Merge
 
 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
@@ -331,6 +353,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.
 
+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
@@ -413,7 +439,9 @@ verify template accepts neither a branch nor a stream parameter.
 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.
 
 :Template Name: {project-name}-packagecloud-release-verify
 
@@ -447,7 +475,12 @@ This template supports PackageCloud release jobs.
 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.
+
+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