+++ /dev/null
-[all]
-ignore = .tox/**,
- .git/**,
- .gitignore,
- .gitreview,
- .gitmodules,
- node_modules/**,
- **.sw?,
- **.orig
-
-[all.Groovy]
-bears = SpaceConsistencyBear
-files = **.groovy
-indent_size = 4
-use_spaces = true
-
-[all.MarkDown]
-bears = MarkdownBear,SpaceConsistencyBear,WriteGoodLintBear
-files = **.md, **.markdown
-use_spaces = true
-
-[all.reStructuredText]
-bears = SpaceConsistencyBear,WriteGoodLintBear
-files = **.rst
-use_spaces = true
-ignore = .git/**,
- .tox/**,
- docs/jjb/lf-ci-jobs.rst,
- docs/jjb/lf-docker-jobs.rst,
- docs/jjb/lf-macros.rst,
- docs/jjb/lf-maven-jobs.rst,
- docs/jjb/lf-rtdv3-jobs.rst
rev: 2.1.1
hooks:
- id: shellcheck
+
+ - repo: local
+ hooks:
+ # TODO: Switch to upstream hook when https://github.com/btford/write-good/pull/119 is merged.
+ - id: write-good
+ name: write-good
+ description: Check docs for English prose with write-good
+ entry: write-good
+ language: node
+ files: "\\.(rst|md|markdown|mdown|mkdn)$"
+ additional_dependencies: ["write-good"]
+ exclude: >
+ (?x)^(
+ docs/jjb/lf-c-cpp-jobs.rst|
+ docs/jjb/lf-ci-jobs.rst|
+ docs/jjb/lf-macros.rst|
+ docs/jjb/lf-python-jobs.rst
+ )$
+
+ # TODO: Switch to upstream hook when https://github.com/btford/write-good/pull/119 is merged.
+ # Files listed below break the following write-good rules:
+ # - adverb weakens meaning
+ # - is wordy or unneeded
+ #
+ # This allows us to place an exception need to pass the check without disabling all checks for
+ # the whole file.
+ # In an ideal world write-good would give us an override for each individual instance of a
+ # violation but until then this gives us a close enough approach.
+ - id: write-good
+ name: write-good --no-adverb --no-tooWordy
+ description: Check docs for English prose with write-good
+ entry: write-good --no-adverb --no-tooWordy
+ language: node
+ files: docs/jjb/lf-ci-jobs.rst
+ additional_dependencies: ["write-good"]
+
+ # TODO: Switch to upstream hook when https://github.com/btford/write-good/pull/119 is merged.
+ # Files listed below break the following write-good rules:
+ # - is wordy or unneeded
+ #
+ # This allows us to place an exception need to pass the check without disabling all checks for
+ # the whole file.
+ # In an ideal world write-good would give us an override for each individual instance of a
+ # violation but until then this gives us a close enough approach.
+ - id: write-good
+ name: write-good --no-tooWordy
+ description: Check docs for English prose with write-good
+ entry: write-good --no-tooWordy
+ language: node
+ files: >
+ (?x)^(
+ docs/jjb/lf-c-cpp-jobs.rst|
+ docs/jjb/lf-macros.rst|
+ docs/jjb/lf-python-jobs.rst
+ )$
+ additional_dependencies: ["write-good"]
Gerrit Branch Lock
------------------
-Job submits a patch to lock or unlock a project's branch. This should only be
-loaded once, as "ci-management-gerrit-branch-lock" (or "ci-management"
-equivalent). That job will process lock/unlock requests for all projects and
-all branches.
+Job submits a patch to lock or unlock a project's branch.
+
+This job will process lock/unlock requests for all projects and all branches
+and does not need to have per-project configuration.
:Template Names:
- {project-name}-gerrit-branch-lock
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally
- should be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:Optional parameters:
Typically this template is automatically pulled in by the
"{project-name}-ci-jobs" job-group and does not need to be explicitly called if
-the job group is being used.
+you are already using the job group.
Minimal Example:
Global Environment Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Global Environment Variables are managed via the
+Manage Global Environment Variables via the
``jenkins-config/global-vars-SILO.sh`` file in ci-management. Replace SILO with
the name of the Jenkins silo the variable configuration is for.
Cloud Configuration
^^^^^^^^^^^^^^^^^^^
-This configuration requires the OpenStack Cloud plugin in Jenkins and is
-currently the only cloud plugin supported.
+This configuration requires the **OpenStack Cloud plugin** in Jenkins.
OpenStack Cloud plugin version supported:
* 2.30 - 2.34
* 2.35 - 2.37
-Cloud configuration are managed via a directory structure in ci-management as
-follows:
+Cloud configuration follows a directory structure in ci-management like this:
- jenkins-config/clouds/openstack/
-- jenkins-config/clouds/openstack/cattle/cloud.cfg
-- jenkins-config/clouds/openstack/cattle/centos7-builder-2c-2g.cfg
-- jenkins-config/clouds/openstack/cattle/centos7-builder-4c-4g.cfg
-- jenkins-config/clouds/openstack/cattle/centos7-docker-4c-4g.cfg
+- jenkins-config/clouds/openstack/**cattle**/cloud.cfg
+- jenkins-config/clouds/openstack/**cattle**/centos7-builder-2c-2g.cfg
+- jenkins-config/clouds/openstack/**cattle**/centos7-builder-4c-4g.cfg
+- jenkins-config/clouds/openstack/**cattle**/centos7-docker-4c-4g.cfg
-The directory name inside of the "openstack" directory is used as the name of
-the cloud configuration. In this case "cattle" is being used as the cloud name.
+This job uses the directory name of the directory inside of the "openstack"
+directory as the name of the cloud configuration in Jenkins. This is to support
+systems that want to use more than one cloud provider. In this example "cattle"
+is the cloud name.
The ``cloud.cfg`` file is a special file used to configure the main cloud
configuration in the format ``KEY=value``.
.. note::
- In the case of template definitions of a parameter below is not passed
- the one defined in default clouds will be inherited.
+ Parameters below that are not defined will inherit the ones defined in
+ the default clouds configuration.
:IMAGE_NAME: The image name to use for this template. (required)
:HARDWARE_ID: OpenStack flavor to use. (required)
:NETWORK_ID: OpenStack network to use. (default: "")
:USER_DATA_ID: User Data to pass into the instance.
(default: jenkins-init-script)
- :INSTANCE_CAP: Total number of instances of this type that can be launched
- at one time. When defined in clouds.cfg it defines the total for the
- entire cloud. (default: null)
- :SANDBOX_CAP: Total number of instances of this type that can be launched
- at one time. When defined in clouds.cfg it defines the total for the
- entire cloud. This applies to "sandbox" systems and overrides the
+ :INSTANCE_CAP: Total number of instances of this type that is available for
+ use at one time. When defined in clouds.cfg it defines the total for
+ the entire cloud. (default: null)
+ :SANDBOX_CAP: Total number of instances of this type that is available for
+ use at one time. When defined in clouds.cfg it defines the total for
+ the entire cloud. This applies to "sandbox" systems and overrides the
INSTANCE_CAP setting. (default: null)
:FLOATING_IP_POOL: Floating ip pool to use. (default: "")
:SECURITY_GROUPS: Security group to use. (default: "default")
:AVAILABILITY_ZONE: OpenStack availability zone to use. (default: "")
- :START_TIMEOUT: Number of milliseconds to wait for the agent to be
- provisioned and connected. (default: 600000)
+ :START_TIMEOUT: Number of milliseconds to wait for agent provisioning.
+ (default: 600000)
:KEY_PAIR_NAME: SSH Public Key Pair to use for authentication.
(default: jenkins-ssh)
:NUM_EXECUTORS: Number of executors to enable for the instance.
:JVM_OPTIONS: JVM Options to pass to Java. (default: null)
:FS_ROOT: File system root for the workspace. (default: "/w")
:NODE_PROPERTIES: Node properties. (default: null)
- :RETENTION_TIME: Number of minutes to wait for an idle slave to be used
- again before it's removed. If set to -1, the slave will be kept
+ :RETENTION_TIME: Number of minutes to wait for an idle minion before
+ removing it from the system. If set to -1, the minion will stick around
forever. (default: 0)
:CONNECTION_TYPE: The connection type for Jenkins to connect to the build
minion. Valid options: JNLP, SSH. (default: "SSH")
:Cloud Configuration:
- The directory ``groovy-inserts`` contains the groovy script output that is
- used to push to Jenkins. In the event of a job failure this file can be
- inspected.
+ The directory ``groovy-inserts`` contains the groovy script output used by
+ Jenkins to push the cloud configuration. In the event of a job failure use
+ this file to debug.
+
.. _lf-global-jjb-jenkins-cfg-verify:
:branch: Git branch to build against. (default: master)
:git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
-This job is not part of the "{project-name}-ci-jobs" group. It must be called
-explicitly.
+This job is not part of the "{project-name}-ci-jobs" group and requires
+separate configuration.
Example:
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally
- should be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:Optional parameters:
.. note::
- The JJB Deploy Job is configured to trigger only if the Gerrit comment
- starts with the `jjb-deploy` keyword.
+ The JJB Deploy Job is a manual job and triggers via Gerrit comment
+ which starts with the ``jjb-deploy`` keyword.
- Example of a valid command in Gerrit comment that triggers the job:
+ Example of a valid command in Gerrit comment that triggers the job:
- ``jjb-deploy builder-jjb-*``
+ ``jjb-deploy builder-jjb-*``
- Example of a invalid command in Gerrit comment that would _not_ trigger
- the job:
+ Example of a invalid command in Gerrit comment that would _not_ trigger
+ the job:
- ``Update the job. jjb-deploy builder-jjb-*``
+ ``Update the job. jjb-deploy builder-jjb-*``
- JOB_NAME can include the * wildcard character to push multiple jobs
- matching the pattern. For example ``jjb-deploy builder-jjb-*`` will push
- all builder-jjb-* jobs to the sandbox system.
+ JOB_NAME can include the ``*`` wildcard character to push jobs matching
+ the pattern. For example ``jjb-deploy builder-jjb-*`` will push all
+ builder-jjb-* jobs to the sandbox system.
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally
- should be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:Optional parameters:
JJB Merge
---------
-Runs `jenkins-jobs update` to update production job configuration
+Runs ``jenkins-jobs update`` to update production job configuration
:Template Names:
- {project-name}-jjb-merge
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:Optional parameters:
:git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
:jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
:jjb-workers: Number of threads to run **update** with. Set to 0 by default
- which is equivalent to the number of available CPU cores. (default: 0)
+ which will use the number of available CPU cores. (default: 0)
:jjb-version: JJB version to install. (default: see job-template)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
(default: false)
:gerrit_merge_triggers: Override Gerrit Triggers.
- :gerrit_trigger_file_paths: Override file paths which can be used to
- filter which file modifications will trigger a build.
+ :gerrit_trigger_file_paths: Override file paths to filter which file
+ modifications will trigger a build.
(default defined by lf_jjb_common)
JJB Verify
----------
-Runs `jenkins-jobs test` to validate JJB syntax. Optionally validates
+Runs ``jenkins-jobs test`` to verify JJB syntax. Optionally verifies
build-node labels used in templates and job definitions.
:Template Names:
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:Optional parameters:
:branch: Git branch to fetch for the build. (default: master)
- :build-concurrent: Whether or not to allow this job to run multiple jobs
+ :build-concurrent: Set to ``true`` to allow this job to run jobs
simultaneously. (default: true)
:build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
:build-node-label-check: Whether to check build-node labels in jobs
:git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
:jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
:jjb-version: JJB version to install. (default: see job-template)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
- :submodule-recursive: Whether to checkout submodules recursively.
+ :submodule-recursive: Set to ``true`` to checkout submodules recursively.
(default: true)
:submodule-timeout: Timeout (in minutes) for checkout operation.
(default: 10)
:submodule-disable: Disable submodule checkout operation.
(default: false)
:throttle_categories: List of categories to throttle by.
- :throttle-enabled: Whether or not to enable throttling on the job.
+ :throttle-enabled: Set to ``true`` to enable throttling on the job.
(default: true)
:throttle-max-per-node: Max jobs to run on the same node. (default: 1)
:throttle-max-total: Max jobs to run across the entire project. - 0
'category'; default: project)
:gerrit_verify_triggers: Override Gerrit Triggers.
- :gerrit_trigger_file_paths: Override file paths which can be used to
- filter which file modifications will trigger a build.
+ :gerrit_trigger_file_paths: Override file paths to filter which file
+ modifications will trigger a build.
(default defined by lf_jjb_common)
.. _jjb-verify-upstream-gjjb:
JJB Verify Upstream Global JJB
------------------------------
-Runs ``jenkins-jobs test`` to validate JJB syntax for upstream global-jjb
+Runs ``jenkins-jobs test`` to verify JJB syntax for upstream global-jjb
patches. This job is useful to notify upstream that they may be breaking
project level jobs.
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:Optional parameters:
:git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
:jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
:jjb-version: JJB version to install. (default: see job-template)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
.. _info-yaml-verify:
Info YAML Verify
----------------
-Info YAML Verify job validates that INFO.yaml file changes are kept isolated from
-other file changes. Verifies INFO.yaml files follow the schema defined in
+This job verifies that ``INFO.yaml`` file changes follow the schema defined in
`lfit/releng-global-jjb/schema/info-schema.yaml`.
+The ``INFO.yaml`` file changes must be independent of any other files changes.
+
:Template Names:
- {project-name}-info-yaml-verify
- gerrit-info-yaml-verify
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:Optional parameters:
:build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
:build-timeout: Timeout in minutes before aborting build. (default: 10)
:git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
LF Pipelines Verify
-------------------
-Verify job for the LF RelEng pipeline library. This can be implemented on any
-Jenkins machine that has the appropriate Pipelines plugins installed. It will
-look for a Gerrit system named "lf-releng" (which should be mapped to
-https://gerrit.linuxfoundation.org/infra/), and pull in the Jenkinsfile in the
-root directory of the repo.
+Verify job for the LF RelEng pipeline library.
+
+Requires the Pipelines plugins installed. This job will look for a Gerrit
+system named "lf-releng" (mapped to https://gerrit.linuxfoundation.org/infra/),
+and pull in the Jenkinsfile in the root directory of the repo.
:Template Names:
- lf-pipelines-verify
:spdx-disable: Disable the SPDX-Identifier checker. (default: false)
:lhc-version: Version of LHC to use. (default: 0.2.0)
:license-exclude-paths: Comma-separated list of paths to exclude from the
- license checker. The paths used here will be matched using a contains
- rule so it is best to be as precise with the path as possible.
- For example a path of '/src/generated/' will be searched as
- '**/src/generated/**'.
+ license checker. Matches the paths defined here using a contains rule,
+ we recommend you to configure as precisely as possible. For example
+ a path of '/src/generated/' will search as '**/src/generated/**'.
Example: org/opendaylight/yang/gen,protobuff/messages
(default: '')
:licenses-allowed: Comma-separated list of allowed licenses.
OpenStack Cron
--------------
-Cron job that runs regularly to perform periodic tasks against OpenStack.
+Cron job that runs on a schedule to perform periodic tasks against OpenStack.
This job requires a Config File Provider file named ``clouds-yaml`` available
containing the credentials for the cloud.
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:jenkins-urls: URLs to Jenkins systems to check for active builds.
:Optional parameters:
:git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
:openstack-cloud: OS_CLOUD setting to pass to openstack client.
(default: vex)
- :openstack-image-cleanup: Whether or not to run the image cleanup script.
+ :openstack-image-cleanup: Set ``true`` to run the image cleanup script.
(default: true)
:openstack-image-cleanup-age: Age in days of image before marking it for
removal. (default: 30)
- :openstack-image-protect: Whether or not to run the image protect script.
+ :openstack-image-protect: Set ``true`` to run the image protect script.
(default: true)
- :openstack-server-cleanup: Whether or not to run the server cleanup script.
+ :openstack-server-cleanup: Set ``true`` to run the server cleanup script.
(default: true)
- :openstack-stack-cleanup: Whether or not to run the stack cleanup script.
+ :openstack-stack-cleanup: Set ``true`` to run the stack cleanup script.
(default: true)
- :openstack-volume-cleanup: Whether or not to run the volume cleanup script.
+ :openstack-volume-cleanup: Set ``true`` to run the volume cleanup script.
(default: true)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
This job finds and updates OpenStack cloud images on the ci-management source
repository.
-The job is triggered in two ways:
+This job functions in 2 ways:
-1. When packer merge job completes, the new image name created is passed
- down to the job.
-2. When the job is triggered manually to update all new images.
+1. When triggered via packer-merge job, updates the image created by the job.
+2. When triggered manually or via cron, updates all images.
-When the job is triggered through an upstream packer merge job, this only
-generates a change request for the new image built.
+When triggered through an upstream packer merge job, this generates a change
+request for the new image built.
-When the job is triggered manually, this job finds the latest images on
-OpenStack cloud and compares them with the images currently used in the source
-ci-management source repository. If the compared images have newer
-time stamps are **all** updated through a change request.
+When triggered manually, this job finds the latest images on OpenStack cloud
+and compares them with the images in use in the source ci-management source
+repository. If the compared images have newer time stamps are **all** updated
+through a change request.
This job requires a Jenkins configuration merge and verify job setup and
working on Jenkins.
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:new-image-name: Name of new image name passed from packer merge job or
set to 'all' to update all images. (default: all)
:git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
:openstack-cloud: OS_CLOUD setting to pass to openstack client.
(default: vex)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:mvn-settings: The name of settings file containing credentials for
the project.
:platforms: Platform or distribution to build. Typically json file
:packer-cloud-settings: Name of settings file containing credentials
for the cloud that packer will build on. (default: packer-cloud-env)
:packer-version: Version of packer to install / use in build. (default: 1.0.2)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
Packer Verify
-------------
-Packer Verify job runs `packer validate` to verify packer configuration. The
+Packer Verify job runs ``packer validate`` to verify packer configuration. The
verify job checks superficial syntax of the template and other files. It does
not attempt to build an image, and cannot detect all possible build issues.
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:mvn-settings: The name of settings file containing credentials for
the project.
:branch: Git branch to fetch for the build. (default: master)
:build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
:build-timeout: Timeout in minutes before aborting build. (default: 10)
- :gerrit_trigger_file_paths: Override file paths which can be used to
- filter which file modifications will trigger a build.
+ :gerrit_trigger_file_paths: Override file paths to filter which file
+ modifications will trigger a build.
:gerrit_verify_triggers: Override Gerrit Triggers.
:git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
:openstack: Packer template uses an OpenStack builder (default: true).
:packer-cloud-settings: Name of settings file containing credentials
for the cloud that packer will build on. (default: packer-cloud-env)
:packer-version: Version of packer to install / use in build. (default: 1.0.2)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
-------------------
Packer Verify Build job is essentially the same as the
-:ref:`Packer Merge job<gjjb-packer-merge>`. It is triggered only by its keyword,
+:ref:`Packer Merge job <gjjb-packer-merge>`. Trigger using its keyword,
and will build a useable image. If the last patch set before a merge has a
successful verify build, the merge job will not build the same image.
:Template Names:
- - {project-name}-packer-verify-build-{platforms}-{templates}
- - gerrit-packer-verify-build
- - github-packer-verify-build
+ - {project-name}-packer-verify-build-{platforms}-{templates}
+ - gerrit-packer-verify-build
+ - github-packer-verify-build
:Comment Trigger: verify-build|packer-build
:Required parameters:
- :build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
- :mvn-settings: The name of settings file containing credentials for
- the project.
- :platforms: Platform or distribution to build. Typically json file
- found in the packer/vars directory. (Example: centos-7)
- :templates: System template to build. Typically a yaml file or shell script
- found in the packer/provision directory. (Example: docker)
+ :build-node: The node to run build on.
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in
+ defaults.yaml)
+ :mvn-settings: The name of settings file containing credentials for
+ the project.
+ :platforms: Platform or distribution to build. Typically json file
+ found in the packer/vars directory. (Example: centos-7)
+ :templates: System template to build. Typically a yaml file or shell script
+ found in the packer/provision directory. (Example: docker)
:Optional parameters:
- :branch: Git branch to fetch for the build. (default: master)
- :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
- :build-timeout: Timeout in minutes before aborting build. (default: 10)
- :gerrit_trigger_file_paths: Override file paths which can be used to
- filter which file modifications will trigger a build.
- :gerrit_verify_triggers: Override Gerrit Triggers.
- :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
- :openstack: Packer template uses an OpenStack builder (default: true).
- :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
- (default: vex).
- :packer-cloud-settings: Name of settings file containing credentials
- for the cloud that packer will build on. (default: packer-cloud-env)
- :packer-version: Version of packer to install / use in build. (default: 1.0.2)
- :stream: Keyword that can be used to represent a release code-name.
- Often the same as the branch. (default: master)
- :submodule-recursive: Whether to checkout submodules recursively.
- (default: true)
- :submodule-timeout: Timeout (in minutes) for checkout operation.
- (default: 10)
- :submodule-disable: Disable submodule checkout operation.
- (default: false)
- :update-cloud-image: Submit a change request to update new built cloud
- image to Jenkins. (default: false)
+ :branch: Git branch to fetch for the build. (default: master)
+ :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
+ :build-timeout: Timeout in minutes before aborting build. (default: 10)
+ :gerrit_trigger_file_paths: Override file paths to filter which file
+ modifications will trigger a build.
+ :gerrit_verify_triggers: Override Gerrit Triggers.
+ :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
+ :openstack: Packer template uses an OpenStack builder (default: true).
+ :openstack-cloud: Sets OS_CLOUD variable to the value of this parameter.
+ (default: vex).
+ :packer-cloud-settings: Name of settings file containing credentials
+ for the cloud that packer will build on. (default: packer-cloud-env)
+ :packer-version: Version of packer to install / use in build. (default: 1.0.2)
+ :stream: Keyword that represents a release code-name.
+ Often the same as the branch. (default: master)
+ :submodule-recursive: Whether to checkout submodules recursively.
+ (default: true)
+ :submodule-timeout: Timeout (in minutes) for checkout operation.
+ (default: 10)
+ :submodule-disable: Disable submodule checkout operation.
+ (default: false)
+ :update-cloud-image: Submit a change request to update new built cloud
+ image to Jenkins. (default: false)
Puppet Verify
-------------
-Runs puppet-lint in the ``puppet-dir`` directory. puppet-lint runs recursively,
-the base directory is usually the best place to run from.
+Runs puppet-lint in the ``puppet-dir`` directory. Since ``puppet-lint`` runs
+recursively, we recommend to run from the base directory.
:Template Names:
Requires ``SonarQube Scanner for Jenkins``
-One of the optional parameters sonar-project-file and sonar-properties
-must be supplied; they cannot both be empty.
+Configuration must set one of the parameters ``sonar-project-file`` or
+``sonar-properties``; they cannot both be empty.
Plug-in configurations
Manage Jenkins --> Configure System --> SonarQube servers
- Install automatically
- Select latest version
-.. note:: Sonar properties can be set directly in the job definition by
- setting the sonar-project-file to ``""`` and adding all properties under
- ``sonar-properties``.
+.. note::
+
+ Optionally, set Sonar properties directly in the job definition by
+ setting the sonar-project-file to ``""`` and adding all properties under
+ ``sonar-properties``.
:Template Names:
The same as the Sonar job above, except the caller also defines a builder
called ``lf-sonar-prescan``, in which they can put any builders that they want
-to run prior to the Sonar scan.
+to run before the Sonar scan.
.. code-block:: yaml
- github-sonar-prescan
:Required Parameters:
- :lf-sonar-prescan: A builder that will run prior to the Sonar scan.
+ :lf-sonar-prescan: A builder that will run before the Sonar scan.
:Optional Parameters:
:sonar-task: Sonar task to run. (default: "")
-------------------------
The same as the Sonar job above, except the caller must supply a shell script
-to run prior to the Sonar scan. This is commonly used to install prerequisites,
+to run before the Sonar scan. This is commonly used to install prerequisites,
build the project, execute unit tests and generate a code-coverage report.
:Template Names:
- github-sonar-prescan-script
:Required Parameters:
- :sonar-prescan-script: A shell script that will run prior to the Sonar scan.
+ :sonar-prescan-script: A shell script that will run before the Sonar scan.
:Optional Parameters:
:sonar-task: Sonar task to run. (default: "")
'container-tag-method' parameter using the global-jjb script
docker-get-container-tag.sh. Use one of the following methods:
-If container-tag-method: latest, the literal string 'latest' is used.
+If ``container-tag-method: latest``, uses the literal string ``latest``.
-If container-tag-method: git-describe, the tag is obtained using the
-git describe command on the repository, which requires that the repository
+If ``container-tag-method: git-describe``, reads the tag from the
+``git describe`` command on the repository, which requires that the repository
has a git tag. For example, if the most recent tag is 'v0.48.1', this
method yields a string like 'v0.48.1' or 'v0.48.1-25-gaee2dcb'.
-If container-tag-method: yaml-file, the tag is obtained from the YAML file
-'container-tag.yaml' in the docker-root directory using the top-level entry
+If ``container-tag-method: yaml-file``, reads the tag from the YAML file
+``container-tag.yaml`` in the docker-root directory using the top-level entry
'tag'. Alternately specify the directory with the YAML file in parameter
'container-tag-yaml-dir'. An example file appears next.
Docker Verify
-------------
-Executes a docker build task to verify that an image can be constructed,
-and discards the image upon completion.
+Executes a docker build task to verify an test image build and discards the
+test image upon completion.
:Template Names:
:build-node: The node to run build on.
:container-public-registry: Docker registry source with base images.
:docker-name: Name of the Docker image.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:mvn-settings: Maven settings.xml file containing Docker credentials.
:Optional parameters:
:build-timeout: Timeout in minutes before aborting build. (default: 60)
:container-tag-method: Specifies the docker tag-choosing method.
Options are "latest", "git-describe" or "yaml-file".
- Option latest simply applies that string.
+ Option latest uses the "latest" tag.
Option git-describe uses the string returned by git-describe,
which requires a tag to exist in the repository.
Option yaml-file uses the string from file "container-tag.yaml"
in the repository. (default: latest)
:container-tag-yaml-dir: Directory with container-tag.yaml. (default: $DOCKER_ROOT)
- :docker-build-args: Additional arguments for the docker build command.
+ :docker-build-args: Arguments for the docker build command.
:docker-get-container-tag-script: Path to script that chooses docker tag.
(default: ../shell/docker-get-container-tag.sh in global-jjb)
:docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root)
:git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
:pre_docker_build_script: Build script to execute before the main verify
- builder steps. (default: a string with only a comment)
+ builder steps. (default: "")
:post_docker_build_script: Build script to execute after the main verify
- builder steps. (default: a string with only a comment)
- :stream: Keyword that can be used to represent a release code-name.
+ builder steps. (default: "")
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
(default: 10)
:gerrit_verify_triggers: Override Gerrit Triggers.
- :gerrit_trigger_file_paths: Override Gerrit file paths which can be
- used to filter which file modifications will trigger a build.
- :github_included_regions: Override Github file paths which can be
- used to filter which file modifications will trigger a build;
- must match parameter gerrit_trigger_file_paths
+ :gerrit_trigger_file_paths: Override Gerrit file paths to filter which file
+ modifications will trigger a build.
+ :github_included_regions: Override Github file paths to filter which file
+ modifications will trigger a build; must match parameter
+ gerrit_trigger_file_paths
container-tag.yaml example:
Executes a docker build task and pushes the resulting image to the specified
Docker registry. If every image is a release candidate, this should use a
-staging repository and should also run regularly to check dependencies.
+staging repository and occassionally run to check dependencies.
:Template Names:
:container-public-registry: Docker registry source with base images.
:container-push-registry: Docker registry target for the push action.
:docker-name: Name of the Docker image.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured
+ in defaults.yaml)
:mvn-settings: Maven settings.xml file containing Docker credentials.
:Optional parameters:
:build-timeout: Timeout in minutes before aborting build. (default: 60)
:container-tag-method: Specifies the docker tag-choosing method.
Options are "latest", "git-describe" or "yaml-file".
- Option latest simply applies that string.
+ Option latest uses the "latest" tag.
Option git-describe uses the string returned by git-describe,
which requires a tag to exist in the repository.
Option yaml-file uses the string from file "container-tag.yaml"
supports multiline input via YAML pipe | character in cases where
one may want to provide more than 1 cron timer. Use '@daily' to run
daily or '@weekly' to run weekly. (default: @weekly)
- :docker-build-args: Additional arguments for the docker build command.
+ :docker-build-args: Arguments for the docker build command.
:docker-get-container-tag-script: Path to script that chooses docker tag.
(default: ../shell/docker-get-container-tag.sh in global-jjb)
:docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root)
:git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
:pre_docker_build_script: Build script to execute before the main merge
- builder steps. (default: a string with only a comment)
+ builder steps. (default: "")
:post_docker_build_script: Build script to execute after the main merge
- builder steps. (default: a string with only a comment)
- :stream: Keyword that can be used to represent a release code-name.
+ builder steps. (default: "")
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
(default: 10)
:gerrit_merge_triggers: Override Gerrit Triggers.
- :gerrit_trigger_file_paths: Override Gerrit file paths which can be
- used to filter which file modifications will trigger a build.
- :github_included_regions: Override Github file paths which can be
- used to filter which file modifications will trigger a build;
- must match parameter gerrit_trigger_file_paths
+ :gerrit_trigger_file_paths: Override Gerrit file paths to filter which file
+ modifications will trigger a build.
+ :github_included_regions: Override GitHub file paths to filter which file
+ modifications will trigger a build; must match parameter
+ gerrit_trigger_file_paths
Sample container-tag.yaml File
------------------------------
This macro will fetch all patches provided via comment trigger and will
create a list of projects from those patches via environment variable
-called DEPENDENCY_BUILD_ORDER which can be used if necessary to build
-projects in the specified order. The order is determined by first patch
-instance for a project in the patch list.
+called ``DEPENDENCY_BUILD_ORDER`` to build projects in the specified order.
+Order calculated by the first patch instance for a project in the patch list.
lf-license-check
----------------
:spdx-disable: Disable the SPDX-Identifier checker.
:lhc-version: Version of LHC to use.
:license-exclude-paths: Comma-separated list of paths to exclude from the
- license checker. The paths used here will be matched using a contains
- rule so it is best to be as precise with the path as possible.
- For example a path of '/src/generated/' will be searched as
- '**/src/generated/**'.
+ license checker. Matches the paths defined here using a contains rule,
+ we recommend you to configure as precisely as possible. For example
+ a path of '/src/generated/' will search as '**/src/generated/**'.
Example: org/opendaylight/yang/gen,protobuff/messages
:licenses-allowed: Comma-separated list of allowed licenses.
For example: Apache-2.0,EPL-1.0,MIT
:DOCKER_REGISTRY: The DNS address of the registry (IP or FQDN)
ex: nexus3.example.com (GLOBAL variable)
- :REGISTRY_PORTS: Required if DOCKER_REGISTRY is set. Space separated list
- of the registry ports to login to. ex: 10001 10002 10003 10004
+ :REGISTRY_PORTS: Required when setting ``DOCKER_REGISTRY``. Space-separated
+ list of the registry ports to login to. ex: 10001 10002 10003 10004
(GLOBAL variable)
- :DOCKERHUB_EMAIL: If this variable is set then an attempt to login to
- DockerHub (docker.io) will be also made. It should be set to the email
- address for the credentials that will get looked up. Only _one_
- credential will ever be found in the maven settings file for DockerHub.
- (GLOBAL variable)
+ :DOCKERHUB_EMAIL: If set, then the job will attempt to login to DockerHub
+ (docker.io). Set to the email address for the credentials that will
+ get looked up. Returns the _first_ credential from the maven settings
+ file for DockerHub. (GLOBAL variable)
lf-infra-gpg-verify-git-signature
---------------------------------
lf-infra-packer-validate
------------------------
-Run `packer validate` to verify packer configuration.
+Run ``packer validate`` to verify packer configuration.
:Required parameters:
:Required parameters:
- :mvn-central: Whether or not to upload to mvn-central. (true|false)
+ :mvn-central: Set to ``true`` to upload to mvn-central. (true|false)
:mvn-global-settings: The name of the Maven global settings to use for
Maven configuration. (default: global-settings)
:mvn-settings: The name of settings file containing credentials for the
lf-maven-install
----------------
-Call maven-target builder with a goal of --version to force Jenkins to
-install the need provided version of Maven. This is needed for any shell scripts
-that want to use Maven.
+Call maven-target builder with a goal of ``--version`` to force Jenkins to
+install the declared version of Maven. Use this as a preparation step for
+any shell scripts that want to use Maven.
:Required parameters:
Call pip install to install packages into a virtualenv located in
/tmp/v/VENV
-.. note:: The first package listed in PIP_PACKAGES is used as the VENV name.
+.. note:: Uses the first package listed in PIP_PACKAGES as the VENV name.
.. _lf-provide-maven-settings:
lf-provide-maven-settings-cleanup
---------------------------------
-Cleanup maven settings.xml configuration. This should be called at the end of
-any macros that calles the
+Cleanup maven ``settings.xml`` configuration. Set at the end of any macros that
+calls the
:ref:`lf-provide-maven-settings <lf-provide-maven-settings>` macro.
lf-rtd-trigger-build
Runs tox to verify that the docs are good and then runs the RTDv3 shell script.
This script handles creating projects as needed, assiging subprojects to the main
read the docs project and triggering builds to update the documentation.
-Jobs will run but skip verify bits until a .readthedocs.yaml is found in the root
-of their repository.
+Jobs will run but skip verify bits until a ``.readthedocs.yaml`` exists in the
+root of their repository.
check-info-votes
----------------
-Calls shell script to validate votes on a change to an INFO.yaml
+Validates votes on a changes to ``INFO.yaml``.
lf-release
----------
Requires ``SIGUL_BRIDGE_IP`` configured as a global envvar.
:Required Parameters:
- :sign-artifacts: Whether or not to sign artifacts with Sigul.
+ :sign-artifacts: Set ``true`` to sign artifacts with Sigul.
:sign-dir: Directory to sign.
:sign-mode: serial|parallel
lf-infra-provide-docker-cleanup
-------------------------------
-Forcibly removes all of the docker images.
+Forcefully removes all docker images.
lf-infra-sonar
---------------
Requires ``SonarQube Scanner for Jenkins``
-.. note:: Sonar properties can be set directly in the job definition by
- setting the sonar-project-file to ``""`` and adding all properties under
- ``sonar-properties``.
+.. note::
+
+ Optionally, set Sonar properties directly in the job definition by
+ setting the sonar-project-file to ``""`` and adding all properties under
+ ``sonar-properties``.
:Optional Parameters:
:sonar-task: Sonar task to run. (default: "")
lf-infra-sonar-with-prescan
---------------------------
-Runs Jenkins SonarQube plug-in after a pre-scan builder, which is defined by
-the macro's caller.
+Runs Jenkins SonarQube plug-in after a pre-scan builder.
Requires ``SonarQube Scanner for Jenkins``
-.. note:: Sonar properties can be set directly in the job definition by
- setting the sonar-project-file to ``""`` and adding all properties under
- ``sonar-properties``.
+.. note::
+
+ Optionally, set Sonar properties directly in the job definition by
+ setting the sonar-project-file to ``""`` and adding all properties under
+ ``sonar-properties``.
:Required Parameters:
- :lf-sonar-prescan: A builder that will run prior to the Sonar scan.
+ :lf-sonar-prescan: A builder that will run before the Sonar scan.
:Optional Parameters:
:sonar-task: Sonar task to run. (default: "")
lf-autotools-parameters
-----------------------
-Provides parameters needed by configure and make. Should be used by any jobs
-that need to call the ``configure && make`` pattern.
+Provides parameters needed by configure and make. Use in any jobs that need to
+call the ``configure && make`` pattern.
lf-clm-parameters
-----------------
lf-cmake-parameters
-------------------
-Provides parameters needed by CMake. Should be used by any jobs that need to
-call the ``cmake && make && make install`` pattern.
+Provides parameters required by CMake. Use in any jobs that need to call the
+``cmake && make && make install`` pattern.
lf-infra-maven-parameters
-------------------------
-Provides parameters needed by Maven. Should be used by any jobs that need to
-call the mvn cli.
+Provides parameters required by Maven. Use in any jobs that need to call the
+``mvn`` CLI.
lf-infra-openstack-parameters
-----------------------------
lf-infra-parameters
-------------------
-Standard parameters used in the LF CI environments. Gerrit variables are
-not used by GitHub projects, but defining them is not harmful. Should be used
-in every job template.
+Standard parameters used in the LF CI environments. GitHub projects will ignore
+the Gerrit variables and vice-versa, so defining them is not harmful. Use in
+every job template.
lf-infra-node-parameters
------------------------
-Provides parameters needed by NodeJS and NPM. Should be used by any jobs that
-need to run NodeJS or NPM.
+Provides parameters needed by NodeJS and NPM. Use in any jobs that need to run
+NodeJS or NPM.
lf-infra-tox-parameters
-----------------------
-Provides parameters needed by python-tox. Should be used by any jobs that need
-to run `tox <https://tox.readthedocs.io>`.
+Provides parameters required by python-tox. Use in any jobs that need to run
+`tox <https://tox.readthedocs.io>`.
lf-build-with-parameters-maven-release
-------------------
Configures the build-discarder plugin for Jenkins with the recommended lf-infra
-settings. Should be used in all job-templates.
+settings. We recommend to include in all job-templates.
Publishers
==========
lf-infra-publish
----------------
-Provides basic lf-infra recommended publisher configurations which should be
-used in all job templates. This primary objective of this trigger is to
-gather package listing, instance metadata, sar reports, build logs and copy
-them to a log server.
+Provides basic lf-infra recommended publisher configurations for use in all job
+templates. The purpose of this trigger is to gather package listing, instance
+metadata, sar reports, build logs and copy them to a log server.
lf-infra-publish-windows
------------------------
Basic SCM configuration for GitHub based projects.
-On the `branch` variable you can assign `$sha1` or `$ghprbActualCommit`
-as the value. This will require that the job be triggered via
-the GHPRB plugin and not manually.
+On the `branch` variable you can assign ``$sha1`` or ``$ghprbActualCommit``
+as the value. This will enable the jobs to trigger via the GHPRB plugin.
:Required parameters:
lf-infra-wrappers-common
------------------------
-Provides lf-infra recommended wrappers which should be used in every
-job-template. It's meant to be used by more specific wrappers below.
+Provides lf-infra recommended wrappers for use in every job-template. Include
+this wrapper when creating more specific platform wrappers to ensure they pick
+up the common settings.
lf-infra-wrappers
-----------------
-Provides lf-infra recommended wrappers which should be used in every
-job-template that's run on Linux systems.
+Provides lf-infra recommended wrappers for use in every job-template targetting
+Linux systems.
-This wrapper requires that a managed file called `npmrc` exists in the Jenkins.
-The main use case here is to point to a npm proxy, on Nexus for example.
-The type of the file should be "Custom file". You can set various npmrc
-settings in it. Documentation on npm configuration can be found at
-https://docs.npmjs.com/files/npmrc. If you are not using npm then it is fine
-for the file to be empty.
+This wrapper requires a managed file named ``npmrc`` to exist in Jenkins. The
+main use case here is to point to a npm proxy, on Nexus for example. Set the
+file type to "Custom file". You can set any npmrc settings in it,
+documentation on npm configuration is available at
+<https://docs.npmjs.com/files/npmrc>. If you are not using npm then create an
+empty file.
Example npmrc:
lf-infra-wrappers-windows
-------------------------
-Provides lf-infra recommended wrappers which should be used in every
-job-template that's run on Windows systems.
+Provides lf-infra recommended wrappers for use in every job-template targetting
+Windows systems.
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in defaults.yaml)
:mvn-settings: The name of settings file containing credentials for the project.
:Optional parameters:
:mvn-goals: The maven goals to perform for the build.
(default: clean install)
:mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
- :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
+ :mvn-params: Parameters to pass to the mvn CLI. (default: '')
:mvn-version: Version of maven to use. (default: mvn35)
:nexus-iq-namespace: Insert a namespace to project AppID for projects that
share a Nexus IQ system to avoid project name collision. We recommend
inserting a trailing - dash if using this parameter.
For example 'odl-'. (default: '')
- :nexus-iq-stage: Stage the policy evaluation will be run against on
- the Nexus IQ Server. (default: 'build')
- :stream: Keyword that can be used to represent a release code-name.
+ :nexus-iq-stage: Sets the **stage** which the policy evaluation will run
+ against on the Nexus IQ Server. (default: 'build')
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
Produces and publishes javadocs for a Maven project.
-Expects javadocs to be available in $WORKSPACE/target/site/apidocs, unless
-the mvn-dir parameter is supplied, in which case expects javadocs to be
-available in $WORKSPACE/{mvn-dir}/target/site/apidocs.
+Expects javadocs to be available in ``$WORKSPACE/target/site/apidocs``, but
+overrideable with the ``mvn-dir`` parameter. If set, will search for javadocs
+in ``$WORKSPACE/{mvn-dir}/target/site/apidocs``.
:Template Names:
:build-node: The node to run build on.
:javadoc-path: The path in Nexus to deploy javadoc to.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in defaults.yaml)
:mvn-settings: The name of settings file containing credentials for the project.
:mvn-site-id: Maven Server ID from settings.xml to pull credentials from.
- (Note: This setting should be configured in defaults.yaml.)
+ (Note: This setting is generally configured in ``defaults.yaml``.)
:Optional parameters:
:mvn-global-settings: The name of the Maven global settings to use for
Maven configuration. (default: global-settings)
:mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
- :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
+ :mvn-params: Parameters to pass to the mvn CLI. (default: '')
Must not include a "-f" option; see parameter mvn-dir.
:mvn-version: Version of maven to use. (default: mvn35)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
Produces javadocs for a Maven project.
-Expects javadocs to be available in $WORKSPACE/target/site/apidocs, unless
-the mvn-dir parameter is supplied, in which case expects javadocs to be
-available in $WORKSPACE/{mvn-dir}/target/site/apidocs.
+Expects javadocs to be available in ``$WORKSPACE/target/site/apidocs``, but
+overrideable with the ``mvn-dir`` parameter. If set, will search for javadocs
+in ``$WORKSPACE/{mvn-dir}/target/site/apidocs``.
:Template Names:
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in defaults.yaml)
:mvn-settings: The name of settings file containing credentials for the project.
:Optional parameters:
:mvn-global-settings: The name of the Maven global settings to use for
Maven configuration. (default: global-settings)
:mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
- :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
+ :mvn-params: Parameters to pass to the mvn CLI. (default: '')
Must not include a "-f" option; see parameter mvn-dir.
:mvn-version: Version of maven to use. (default: mvn35)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
This job pushes files to Nexus using cURL instead of allowing the Maven deploy
goal to push the upload. This is to get around the issue that Maven deploy does
not properly support uploading files at the end of the build and instead pushes
-as it goes. There exists a `-Ddeploy-at-end` feature however it does not work
+as it goes. There exists a ``-Ddeploy-at-end`` feature but it does not work
with extensions.
This job uses the following strategy to deploy jobs to Nexus:
-1. `wget -r` to fetch maven-metadata.xml from Nexus
-2. `mvn deploy -DaltDeploymentRepository` to prepare files for upload
+1. ``wget -r`` to fetch maven-metadata.xml from Nexus
+2. ``mvn deploy -DaltDeploymentRepository`` to prepare files for upload
3. Removes untouched maven-metadata.xml files before upload
4. Use lftools (cURL) upload script to push artifacts to Nexus
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in defaults.yaml)
:mvn-settings: The name of settings file containing credentials for the project.
:mvn-snapshot-id: Maven Server ID from settings.xml to pull credentials from.
- (Note: This setting should be configured in defaults.yaml.)
+ (Note: This setting is generally configured in ``defaults.yaml``.)
:nexus-snapshot-repo: The repository id of the Nexus snapshot repo to deploy to.
:Optional parameters:
:mvn-global-settings: The name of the Maven global settings to use for
Maven configuration. (default: global-settings)
:mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
- :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
+ :mvn-params: Parameters to pass to the mvn CLI. (default: '')
:mvn-version: Version of maven to use. (default: mvn35)
:nexus-cut-dirs: Number of directories to cut from file path for `wget -r`.
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
(default: false)
:gerrit_merge_triggers: Override Gerrit Triggers.
- :gerrit_trigger_file_paths: Override file paths which can be used to
- filter which file modifications will trigger a build.
+ :gerrit_trigger_file_paths: Override file paths to filter which file
+ modifications will trigger a build.
Maven Merge for Docker
----------------------
Produces a snapshot docker image in a Nexus registry. Appropriate for
Java projects that do not need to deploy any POM or JAR files.
-Similar to Maven Merge as described above but logs in to Docker
+Like the Maven Merge job as described above but logs in to Docker
registries first and skips the lf-maven-deploy builder. The project
-POM file should invoke a plugin to build and push a Docker image. The
-base image should be pulled from the registry in the environment
-variable CONTAINER_PULL_REGISTRY. The new image should be pushed to the
-registry in the environment variable CONTAINER_PUSH_REGISTRY.
+POM file should invoke a plugin to build and push a Docker image.
+This pulls the base image from the registry in the environment
+variable ``CONTAINER_PULL_REGISTRY`` and pushes new image into the
+registry in the environment variable ``CONTAINER_PUSH_REGISTRY``.
:Template Names:
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in defaults.yaml)
:mvn-settings: The name of settings file containing credentials for the project.
:mvn-staging-id: Maven Server ID from settings.xml to pull credentials from.
- (Note: This setting should be configured in defaults.yaml.)
+ (Note: This setting is generally configured in ``defaults.yaml``.)
:staging-profile-id: Profile ID of the project's Nexus staging profile.
:Optional parameters:
:deploy-path: The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM)
:git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
:java-version: Version of Java to use for the build. (default: openjdk8)
- :mvn-central: Set to 'true' to also stage to OSSRH. This is for projects
- that want to release to Maven Central. If set the parameter
- ``ossrh-profile-id`` also needs to be set. (default: false)
+ :mvn-central: Set to ``true`` to also stage to **OSSRH**. This is for projects
+ that want to release to Maven Central. If set, then also set the parameter
+ ``ossrh-profile-id``. (default: false)
:maven-versions-plugin: Whether to call Maven versions plugin or not. (default: false)
:mvn-global-settings: The name of the Maven global settings to use for
Maven configuration. (default: global-settings)
:mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
- :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
+ :mvn-params: Parameters to pass to the mvn CLI. (default: '')
:mvn-version: Version of maven to use. (default: mvn35)
:ossrh-profile-id: Profile ID for project as provided by OSSRH.
(default: '')
:sign-artifacts: Sign artifacts with Sigul. (default: false)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
(default: version.properties)
:gerrit_release_triggers: Override Gerrit Triggers.
- :gerrit_trigger_file_paths: Override file paths which can be used to
- filter which file modifications will trigger a build.
+ :gerrit_trigger_file_paths: Override file paths to filter which file
+ modifications will trigger a build.
Maven Stage for Docker
----------------------
Appropriate for Java projects that do not need to deploy any POM or
JAR files.
-Similar to Maven Stage as described above but logs in to Docker
+Like the Maven Stage job as described above but logs in to Docker
registries first and skips the lf-maven-deploy builder. The project
-POM file should invoke a plugin to build and push a Docker image. The
-base image should be pulled from the registry in the environment
-variable CONTAINER_PULL_REGISTRY. The new image should be pushed to the
-registry in the environment variable CONTAINER_PUSH_REGISTRY.
+POM file should invoke a plugin to build and push a Docker image.
+This pulls the base image from the registry in the environment
+variable ``CONTAINER_PULL_REGISTRY`` and pushes new image into the
+registry in the environment variable ``CONTAINER_PUSH_REGISTRY``.
:Template Names:
Sonar job which runs mvn clean install then publishes to Sonar.
-This job purposely only runs on the master branch as there are Additional
-configuration needed to support multiple branches and there's not much
-interest in that kind of support.
+This job purposely runs on the ``master`` branch and does not support
+multi-branch configuration.
:Template Names:
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in defaults.yaml)
:mvn-settings: The name of settings file containing credentials for the project.
:Optional parameters:
:mvn-goals: The maven goals to perform for the build.
(default: clean install)
:mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
- :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
+ :mvn-params: Parameters to pass to the mvn CLI. (default: '')
:mvn-version: Version of maven to use. (default: mvn35)
:sonar-mvn-goals: Maven goals to run for sonar analysis.
(default: sonar:sonar)
- :sonarcloud: Whether or not to use SonarCloud ``true|false``.
+ :sonarcloud: Set to ``true`` 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: '')
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in defaults.yaml)
:mvn-settings: The name of settings file containing credentials for the project.
:Optional parameters:
:mvn-global-settings: The name of the Maven global settings to use for
Maven configuration. (default: global-settings)
:mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
- :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
+ :mvn-params: Parameters to pass to the mvn CLI. (default: '')
:mvn-version: Version of maven to use. (default: mvn35)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
(default: false)
:gerrit_verify_triggers: Override Gerrit Triggers.
- :gerrit_trigger_file_paths: Override file paths which can be used to
- filter which file modifications will trigger a build.
+ :gerrit_trigger_file_paths: Override file paths to filter which file
+ modifications will trigger a build.
Maven Verify for Docker
-----------------------
-Similar to Maven Verify as described above but logs in to Docker
+Like the Maven Verify job as described above but logs in to Docker
registries first. The project POM file should invoke a plugin to build
-a Docker image. The base image should be pulled from the registry in
-the environment variable CONTAINER_PULL_REGISTRY.
+a Docker image. This pulls the base image from the registry in the environment
+variable ``CONTAINER_PULL_REGISTRY``.
:Template Names:
Verify job which runs mvn clean install to test a project build /w deps
-This job can be used to verify a patch in conjunction to all of the
-upstream patches it depends on. The user of this job can provide a list
-via comment trigger.
+This job's purpose is to verify a patch in conjunction to a list of upstream
+patches it depends on. The user of this job can provide a list of patches via
+comment trigger.
:Template Names:
:Required parameters:
:build-node: The node to run build on.
- :jenkins-ssh-credential: Credential to use for SSH. (Generally should
- be configured in defaults.yaml)
+ :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in defaults.yaml)
:mvn-settings: The name of settings file containing credentials for the project.
:Optional parameters:
:mvn-global-settings: The name of the Maven global settings to use for
Maven configuration. (default: global-settings)
:mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
- :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
+ :mvn-params: Parameters to pass to the mvn CLI. (default: '')
:mvn-version: Version of maven to use. (default: mvn35)
- :stream: Keyword that can be used to represent a release code-name.
+ :stream: Keyword that represents a release code-name.
Often the same as the branch. (default: master)
:submodule-recursive: Whether to checkout submodules recursively.
(default: true)
(default: false)
:gerrit_verify_triggers: Override Gerrit Triggers.
- :gerrit_trigger_file_paths: Override file paths which can be used to
- filter which file modifications will trigger a build.
+ :gerrit_trigger_file_paths: Override file paths to filter which file
+ modifications will trigger a build.
suites. Checking coverage does not guarantee that the tests execute
properly, but it identifies code that is not executed by any test.
-.. comment Start ignoring WriteGoodLintBear
-
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.
-
-.. comment Stop ignoring
+projects, so the job uses the goal ``validate`` by default. The second
+invocation publishes results using the goal ``sonar:sonar`` by default.
For example:
ReadTheDocs Version:3 Jobs
##########################
-ReadTheDocs Projects can be configured in a nested manner, by configuring a
-project as a subproject of another project. This allows for documentation
-projects to share a search index and a namespace or custom domain, but still be
-maintained independently.
+ReadTheDocs supports the nesting of projects, by configuring a project as a
+subproject of another project. This allows for documentation projects to share
+a search index and a namespace or custom domain, while still maintained
+independently of each other.
-The master Read The Docs project files are usually maintained in a
-"docs" git repository and should contain an index with links to all
-the sub-projects. Each sub-project must maintain its documentation
-files in a "docs" subdirectory within that software component's git
-repository.
+The master Read The Docs project files, maintained in a "docs" Git repository
+should contain an index with links to all the sub-projects. Each sub-project
+must maintain its documentation files in a "docs" subdirectory within that
+software component's Git repository.
The RTDv3 Jenkins jobs publish documentation by triggering builds at
ReadTheDocs.io. That build process clones the appropriate repository
and transforms reStructuredText (RST) and other files into HTML.
-All project's Read the Docs builds are performed separately from sub-project
-builds.
-
-The Read The Docs site supports multiple versions of documentation for
-the master project and every sub-project. Every project should have a
-development branch that's published at ReadTheDocs under the title
-"latest"; in git this is usually the "master" branch. Most projects
-also declare releases periodically. ReadTheDocs automatically detects
-the creation of git branches and git tags, and publishes the most
-recent one under the title "stable." For more details please see
-`ReadTheDocs Versions
+All project's Read the Docs builds separately from sub-project builds.
+
+The Read The Docs site supports versioned documentation for the master project
+and every sub-project. Every project should have a development branch that's
+published at ReadTheDocs under the title "latest"; in Git this is the "master"
+branch although can be different in some projects. Most projects also declare
+releases periodically. ReadTheDocs automatically detects the creation of git
+branches and git tags, and publishes the most recent one under the title
+"stable." For more details please see `ReadTheDocs Versions
<https://docs.readthedocs.io/en/stable/versions.html>`_. Teams can
control this process using Jenkins job configuration parameters as
discussed below.
User setup
----------
-To transform your rst documentation into a Read The Docs page, this job must be
-configured and created as described in Admin setup below. Once this is complete
-the following files must be added to your repository:
+To transform your rst documentation into a Read The Docs page, configure as
+described in Admin setup below. Once this is complete, add the following files
+to your repository:
.. code-block:: bash
docs/requirements-docs.txt
docs/conf.py
-Rather than have you copy and paste these files from a set of docs here, the
+Rather than copying and pasting these files from a set of docs here, the
following repo contains a script that will do this for you. Please refer to the
-explanation presented in: https://github.com/lfit-sandbox/test. This is all
-currently a beta feature, so feedback is encouraged. The script
-``docs_script.sh`` is not needed, you can copy the files by hand if you prefer.
+explanation presented in: <https://github.com/lfit-sandbox/test>. This is a
+beta feature, so please send feedback on your experiences. Once complete, the
+script ``docs_script.sh`` is not needed. You can copy the files by hand if you
+prefer.
The default location of the tox.ini file is in the git repository root
directory. Optionally your documentation lead may decide to store all tox files
within the required "docs" subdirectory by setting configuration option
"tox-dir" to value "docs/" as discussed below.
-If your project's tox dir is "docs/" and not "." the tox.ini must be
-reconfigured with the correct relative paths.
+If your project's tox dir is ``docs/`` and not ``.``, update the tox.ini
+configuration with the correct relative paths.
-Additionally, you must also modify the doc-dir. For example, from the default
-of ``doc-dir: "docs/_build/html"`` to ``doc-dir: "_build/html"``, as the relative
+You must also set the doc-dir. For example, from the default of
+``doc-dir: "docs/_build/html"`` to ``doc-dir: "_build/html"``, as the relative
path in the tox run has changed.
-
-Once these files are correctly configured in your repository you can build
-the rst files locally to test:
+Once configured, in your repository you can build the rst files locally to
+test:
.. code-block:: bash
If your project does not create branches, you can skip this step.
-For Read The Docs to see your new branch, a build needs to be triggered.
-A trivial change to any file in your project's /docs/ directory
-on your newly minted branch is sufficient to build and activate your project's
-new branch on Read The Docs. This will create a new selectable version
-in the bottom right corner of your project's Read The Docs page.
+For Read The Docs to see your new branch, trigger a build to force RTD to run
+an update. Use a trivial change to any file in your project's ``/docs/``
+directory on your newly minted branch to trigger a build and activate your
+project's new branch on Read The Docs. This will create a new selectable
+version in the bottom right corner of your project's Read The Docs page.
Once all projects have branched the process to release the documentation
(that is to change the default landing point of your docs from /latest/ to /branchname/)
is to change the default-version in the jenkins job config as follows:
Read The Docs v3 api to create projects on the fly, as well as setting up
sub-project associations with the master doc.
-Jobs will run but skip any actual verification until a .readthedocs.yaml is placed in the
-root of the repository
+A ``.readthedocs.yaml`` must exist in the root of the repository otherwise the
+jobs will run but skip actual verification.
-The master doc must be defined in
-jenkins-config/global-vars-{production|sandbox}.sh
+Define the master doc in jenkins-config/global-vars-{production|sandbox}.sh
-Normally this project is called doc or docs or documentation and all other docs build will
-be set as a subproject of this job.
+This project named "doc" or "docs" or "documentation" will set all other docs
+builds as a subproject of this job.
examples:
- master:
branch: '*'
-Github jobs must be per project, and will be covered by a different set of jobs once these are proven.
+GitHub jobs must be per-project. Once proven, a different set of jobs will be available.
Job requires an lftools config section, this is to provide api access to read the docs.
[tox]
minversion = 1.6
envlist =
- coala,
ensure-documented,
jjb,
jjb-compare-xml,
pre-commit
skipsdist = True
-[testenv:coala]
-basepython = python3
-deps =
- coala
- coala-bears
- pygments
- requests
- nodeenv
- numpy
-commands =
- nodeenv -p
- npm install --global remark-cli remark-lint write-good
- coala --non-interactive
-
[testenv:docs]
basepython = python3
deps = -rrequirements.txt
Code Review / releng / global-jjb.git / commitdiff