Merge "Allow id's for different templates to follow same naming"

doc/source/definition.rst

@@ -70,6 +70,10 @@ itself (e.g. ``{name}-unit-tests`` in the above example) will be
 substituted in. This is useful in cases where you need to trace a job
 back to its template.
 
+Sometimes it is useful to have the same job name format used even
+where the template contents may vary. `Ids` provide a mechanism to
+support such use cases.
+
 .. _project:
 
 Project
@@ -282,6 +286,27 @@ always use ``{{`` to achieve a literal ``{``.  A generic builder will need
 to consider the correct quoting based on its use of parameters.
 
 
+.. _ids:
+
+Item ID's
+^^^^^^^^^
+
+It's possible to assign an `id` to any of the blocks and then use that
+to reference it instead of the name. This has two primary functions:
+
+* A unique identifier where you wish to use the same naming format for
+  multiple templates. This allows to follow a naming scheme while
+  still using multiple templates to handle subtle variables in job
+  requirements.
+* Provides a simpler name for a `job-template` where you have multiple
+  variables in the name and don't wish to have to include this information
+  in every use. This also allows changing the template output name without
+  impacting references.
+
+Example:
+
+.. literalinclude::  /../../tests/yamlparser/fixtures/template_ids.yaml
+
 .. _raw:
 
 Raw config

jenkins_jobs/parser.py

@@ -114,11 +114,13 @@ class YamlParser(object):
                     raise JenkinsJobsException("Syntax error, for item "
                                                "named '{0}'. Missing indent?"
                                                .format(n))
-                name = dfn['name']
-                if name in group:
-                    self._handle_dups("Duplicate entry found in '{0}: '{1}' "
-                                      "already defined".format(fp.name, name))
-                group[name] = dfn
+                # allow any entry to specify an id that can also be used
+                id = dfn.get('id', dfn['name'])
+                if id in group:
+                    self._handle_dups(
+                        "Duplicate entry found in '{0}: '{1}' already "
+                        "defined".format(fp.name, id))
+                group[id] = dfn
                 self.data[cls] = group
 
     def parse(self, fn):

tests/yamlparser/fixtures/template_ids.xml

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <actions/>
+  <description>&lt;!-- Managed by Jenkins Job Builder --&gt;</description>
+  <keepDependencies>false</keepDependencies>
+  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
+  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
+  <concurrentBuild>false</concurrentBuild>
+  <canRoam>true</canRoam>
+  <properties/>
+  <scm class="hudson.scm.NullSCM"/>
+  <builders>
+    <hudson.tasks.Shell>
+      <command>echo &quot;Template name: template-test-ids-{num}-{type}&quot;
+echo &quot;Job name: template-test-ids-1-periodic&quot;
+echo &quot;Hello World&quot;
+</command>
+    </hudson.tasks.Shell>
+  </builders>
+  <publishers/>
+  <buildWrappers/>
+</project>
+
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <actions/>
+  <description>&lt;!-- Managed by Jenkins Job Builder --&gt;</description>
+  <keepDependencies>false</keepDependencies>
+  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
+  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
+  <concurrentBuild>false</concurrentBuild>
+  <canRoam>true</canRoam>
+  <properties/>
+  <scm class="hudson.scm.NullSCM"/>
+  <builders>
+    <hudson.tasks.Shell>
+      <command>echo &quot;Template name: template-test-ids-{num}-{type}&quot;
+echo &quot;Job name: template-test-ids-2-canary&quot;
+</command>
+    </hudson.tasks.Shell>
+    <hudson.tasks.Shell>
+      <command>echo &quot;Goodbye World&quot;
+</command>
+    </hudson.tasks.Shell>
+  </builders>
+  <publishers/>
+  <buildWrappers/>
+</project>

tests/yamlparser/fixtures/template_ids.yaml

@@ -0,0 +1,31 @@
+- project:
+    name: test_template_id
+    jobs:
+        - 'simple-template':
+            test_var: Hello World
+            type: periodic
+            num: 1
+        - 'not-as-simple-template':
+            test_var: Goodbye World
+            type: canary
+            num: 2
+
+- job-template:
+    name: 'template-test-ids-{num}-{type}'
+    id: simple-template
+    builders:
+      - shell: |
+         echo "Template name: {template-name}"
+         echo "Job name: template-test-ids-{num}-{type}"
+         echo "{test_var}"
+
+- job-template:
+    name: 'template-test-ids-{num}-{type}'
+    id: not-as-simple-template
+    builders:
+      - shell: |
+         echo "Template name: {template-name}"
+         echo "Job name: template-test-ids-{num}-{type}"
+      - shell: |
+         echo "{test_var}"
+