+
+## Deploying packer-jobs
+
+The packer job group contains jobs to build custom minion images. The minimal
+configuration needed to deploy the packer jobs is as follows which deploys the
+**{project-name}-packer-jobs** job group as defined in **lf-ci-jobs.yaml**.
+
+ci-management.yaml:
+
+```
+- project:
+ name: packer-jobs
+
+ jobs:
+ - '{project-name}-packer-jobs'
+
+ project: ci-management
+ project-name: ci-management
+ branch: master
+ build-node: centos7-basebuild-2c-1g
+
+ platforms:
+ - centos
+ - ubuntu-14.04
+ - ubuntu-16.04
+
+ templates:
+ - devstack
+ - docker
+ - gbp
+ - java-builder
+ - mininet
+
+ exclude:
+ - platforms: centos
+ templates: gbp
+ - platforms: centos
+ templates: mininet
+```
+
+Required parameters:
+
+**project**: is the project repo as defined in source control.
+**project-name**: is a custom name to call the job in Jenkins.
+**build-node**: is the name of the builder to use when building (Jenkins label).
+**platforms**: is a list of supported platforms.
+**templates**: is a list of supported templates.
+
+Optional parameters:
+
+**branch**: is the git branch to build from.
+**packer-version**: is the version of packer to install in the build minion,
+when packer is not available.
+**exclude**: is a combination of platforms and templates which are not required
+to build.
+
+## Deploying Python jobs
+
+We provide the following Python jobs templates:
+
+### {project-name}-tox-verify-{stream}
+
+Use this job to call python-tox to run builds and tests. The most common
+usage of this job is to run the Coala linter against projects.
+
+```
+- project:
+ name: builder
+ jobs:
+ - '{project-name}-tox-verify-{stream}'
+
+ project-name: builder
+ project: releng/builder
+ build-node: centos7-java-builder-2c-4g
+ stream: master
+```
+
+Required parameters:
+
+**project**: is the project repo as defined in source control.
+**project-name**: is a custom name to call the job in Jenkins.
+**build-node**: is the name of the builder to use when building (Jenkins label).
+**stream**: typically `master` or matching the build branch. This
+ is a useful keywords to map a release codename to a branch. For
+ example OpenDaylight uses this to map stream=carbon to
+ branch=stable/carbon.
+
+Optional parameters:
+
+**branch**: is the git branch to build from.
+**jjb-version**: is the version of JJB to install in the build minion.
+**tox-dir**: directory containing tox.ini file (default: '')
+**tox-envs**: tox environments to run (default: '')
+
+## Archiving logs in Jobs
+
+There are 2 ways supported for archiving log information:
+
+1) Job creates $WORKSPACE/archives directory and places logs there
+
+This method pushes the entire archives directory to the log server
+in the same structure as configured in the archives directory.
+
+2) Via job variable ARCHIVE_ARTIFACTS using globstar patterns.
+
+In this method a job can define a globstar for example `**/*.log` which then
+causes the archive script to do a globstar search for that pattern and archives
+any files it finds matching.
+
+## Overriding merge and verify triggers
+
+The default trigger conditions for Merge and Verify job types are overrideable
+in a project configuration by overriding the following variables:
+
+- gerrit_merge_triggers
+- gerrit_verify_triggers
+
+These variables take a list of trigger-on values as defined in JJB docs here:
+<https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit>
+
+## Appendix
+
+### ShellCheck
+
+When using ShellCheck to lint global-jjb or any projects that include
+global-jjb as part of their project (common with ci-management repos) then
+we require version 0.4.x of ShellCheck installed on the build vms. This version
+introduces annotations used by shell scripts in this repo.