{"action":"created","comment":{"url":"https://api.github.com/repos/ClusterHQ/flocker/pulls/comments/37983192","id":37983192,"diff_hunk":"@@ -1,26 +1,134 @@\n-{# jenkins job DSL reference:\n+{# jobs.groovy.j2\n+\n+  This jinja2 template is used to produce a jobs.groovy file containing the\n+  jenkins job DSL plugin code to build all the required views, folders, and\n+  jobs for a particular project in the Jenkins interface.\n+\n+   The full Jenkins job DSL reference can be found on the URL below:\n    https://github.com/jenkinsci/job-dsl-plugin/wiki/Job-reference\n+\n+   The file is consumed by the Jenkins job setup_ClusterHQ_Flocker. That job\n+   contains two build steps, the first executes a python file 'render.py' which\n+   reads the build.yaml file and expands this jobs.groovy.j2 template using\n+   the contents of that yaml dictionary. The resulting jobs.groovy file is then\n+   read by a  second build step of type 'Process Job DSL' which produces all\n+   the jenkins objects.\n+\n+   A typical jenkins job contains the following sections, this is just an\n+   example of possible actions within a particular section:\n+\n+   * Parameters:\n+        - parameters can be added to a job, these are used to pass environment\n+          variables to the build steps or any other step in the job.\n+\n+   * Source Control defintions:\n+        - repository URL\n+        - what SCM tool git/svn/mercurial\n+        - operations to do prior/after a git update/close\n+\n+    * Triggers:\n+        - When to execute the build ?\n+        - On a crontab style\n+        - by pooling the repository for changes\n+        - triggered by GitHub or others\n+\n+   * Wrappers which 'decorate' the build steps of the job\n+        - adds stuff like timestamps to the log output\n+        - sets a timeout and aborts the build when exceeded\n+\n+    * Build steps\n+        - Commonly shell based steps, as in the cli to execute\n+\n+    * Post-Build actions also called Publishers:\n+        - Archiving produced files so that they are made available in other\n+          jobs\n+        - Running coverage or test reports\n+        - Triggering other jobs\n+\n+\n+    The structure of this jinja2 file is as follows:\n+\n+    a set of Jinja2 macro definitions which produce job dsl text for the","path":"jobs.groovy.j2","position":52,"original_position":52,"commit_id":"7922e44cc1bc0d03a36ea8933f4cbf6b32c44de6","original_commit_id":"7922e44cc1bc0d03a36ea8933f4cbf6b32c44de6","user":{"login":"jml","id":125674,"avatar_url":"https://avatars.githubusercontent.com/u/125674?v=3","gravatar_id":"","url":"https://api.github.com/users/jml","html_url":"https://github.com/jml","followers_url":"https://api.github.com/users/jml/followers","following_url":"https://api.github.com/users/jml/following{/other_user}","gists_url":"https://api.github.com/users/jml/gists{/gist_id}","starred_url":"https://api.github.com/users/jml/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jml/subscriptions","organizations_url":"https://api.github.com/users/jml/orgs","repos_url":"https://api.github.com/users/jml/repos","events_url":"https://api.github.com/users/jml/events{/privacy}","received_events_url":"https://api.github.com/users/jml/received_events","type":"User","site_admin":false},"body":"Nit: 'A', not 'a'.","created_at":"2015-08-26T13:50:44Z","updated_at":"2015-08-26T13:50:44Z","html_url":"https://github.com/ClusterHQ/flocker/pull/1886#discussion_r37983192","pull_request_url":"https://api.github.com/repos/ClusterHQ/flocker/pulls/1886","_links":{"self":{"href":"https://api.github.com/repos/ClusterHQ/flocker/pulls/comments/37983192"},"html":{"href":"https://github.com/ClusterHQ/flocker/pull/1886#discussion_r37983192"},"pull_request":{"href":"https://api.github.com/repos/ClusterHQ/flocker/pulls/1886"}}},"pull_request":{"url":"https://api.github.com/repos/ClusterHQ/flocker/pulls/1886","id":43391187,"html_url":"https://github.com/ClusterHQ/flocker/pull/1886","diff_url":"https://github.com/ClusterHQ/flocker/pull/1886.diff","patch_url":"https://github.com/ClusterHQ/flocker/pull/1886.patch","issue_url":"https://api.github.com/repos/ClusterHQ/flocker/issues/1886","number":1886,"state":"open","locked":false,"title":"improve commenting in build.yaml, jobs.groovy.j2","user":{"login":"Azulinho","id":851757,"avatar_url":"https://avatars.githubusercontent.com/u/851757?v=3","gravatar_id":"","url":"https://api.github.com/users/Azulinho","html_url":"https://github.com/Azulinho","followers_url":"https://api.github.com/users/Azulinho/followers","following_url":"https://api.github.com/users/Azulinho/following{/other_user}","gists_url":"https://api.github.com/users/Azulinho/gists{/gist_id}","starred_url":"https://api.github.com/users/Azulinho/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Azulinho/subscriptions","organizations_url":"https://api.github.com/users/Azulinho/orgs","repos_url":"https://api.github.com/users/Azulinho/repos","events_url":"https://api.github.com/users/Azulinho/events{/privacy}","received_events_url":"https://api.github.com/users/Azulinho/received_events","type":"User","site_admin":false},"body":"Added a lot of documentation about the build.yaml and the jobs.groovy.j2","created_at":"2015-08-26T11:27:09Z","updated_at":"2015-08-26T13:50:44Z","closed_at":null,"merged_at":null,"merge_commit_sha":"6f06775b51d631a7c06d4275df356e32858249cc","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/ClusterHQ/flocker/pulls/1886/commits","review_comments_url":"https://api.github.com/repos/ClusterHQ/flocker/pulls/1886/comments","review_comment_url":"https://api.github.com/repos/ClusterHQ/flocker/pulls/comments{/number}","comments_url":"https://api.github.com/repos/ClusterHQ/flocker/issues/1886/comments","statuses_url":"https://api.github.com/repos/ClusterHQ/flocker/statuses/7922e44cc1bc0d03a36ea8933f4cbf6b32c44de6","head":{"label":"ClusterHQ:improve_build_yaml_documentation_FLOC-2933","ref":"improve_build_yaml_documentation_FLOC-2933","sha":"7922e44cc1bc0d03a36ea8933f4cbf6b32c44de6","user":{"login":"ClusterHQ","id":7913449,"avatar_url":"https://avatars.githubusercontent.com/u/7913449?v=3","gravatar_id":"","url":"https://api.github.com/users/ClusterHQ","html_url":"https://github.com/ClusterHQ","followers_url":"https://api.github.com/users/ClusterHQ/followers","following_url":"https://api.github.com/users/ClusterHQ/following{/other_user}","gists_url":"https://api.github.com/users/ClusterHQ/gists{/gist_id}","starred_url":"https://api.github.com/users/ClusterHQ/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ClusterHQ/subscriptions","organizations_url":"https://api.github.com/users/ClusterHQ/orgs","repos_url":"https://api.github.com/users/ClusterHQ/repos","events_url":"https://api.github.com/users/ClusterHQ/events{/privacy}","received_events_url":"https://api.github.com/users/ClusterHQ/received_events","type":"Organization","site_admin":false},"repo":{"id":19248542,"name":"flocker","full_name":"ClusterHQ/flocker","owner":{"login":"ClusterHQ","id":7913449,"avatar_url":"https://avatars.githubusercontent.com/u/7913449?v=3","gravatar_id":"","url":"https://api.github.com/users/ClusterHQ","html_url":"https://github.com/ClusterHQ","followers_url":"https://api.github.com/users/ClusterHQ/followers","following_url":"https://api.github.com/users/ClusterHQ/following{/other_user}","gists_url":"https://api.github.com/users/ClusterHQ/gists{/gist_id}","starred_url":"https://api.github.com/users/ClusterHQ/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ClusterHQ/subscriptions","organizations_url":"https://api.github.com/users/ClusterHQ/orgs","repos_url":"https://api.github.com/users/ClusterHQ/repos","events_url":"https://api.github.com/users/ClusterHQ/events{/privacy}","received_events_url":"https://api.github.com/users/ClusterHQ/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ClusterHQ/flocker","description":"Easily manage Docker containers & their data","fork":false,"url":"https://api.github.com/repos/ClusterHQ/flocker","forks_url":"https://api.github.com/repos/ClusterHQ/flocker/forks","keys_url":"https://api.github.com/repos/ClusterHQ/flocker/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ClusterHQ/flocker/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ClusterHQ/flocker/teams","hooks_url":"https://api.github.com/repos/ClusterHQ/flocker/hooks","issue_events_url":"https://api.github.com/repos/ClusterHQ/flocker/issues/events{/number}","events_url":"https://api.github.com/repos/ClusterHQ/flocker/events","assignees_url":"https://api.github.com/repos/ClusterHQ/flocker/assignees{/user}","branches_url":"https://api.github.com/repos/ClusterHQ/flocker/branches{/branch}","tags_url":"https://api.github.com/repos/ClusterHQ/flocker/tags","blobs_url":"https://api.github.com/repos/ClusterHQ/flocker/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ClusterHQ/flocker/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ClusterHQ/flocker/git/refs{/sha}","trees_url":"https://api.github.com/repos/ClusterHQ/flocker/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ClusterHQ/flocker/statuses/{sha}","languages_url":"https://api.github.com/repos/ClusterHQ/flocker/languages","stargazers_url":"https://api.github.com/repos/ClusterHQ/flocker/stargazers","contributors_url":"https://api.github.com/repos/ClusterHQ/flocker/contributors","subscribers_url":"https://api.github.com/repos/ClusterHQ/flocker/subscribers","subscription_url":"https://api.github.com/repos/ClusterHQ/flocker/subscription","commits_url":"https://api.github.com/repos/ClusterHQ/flocker/commits{/sha}","git_commits_url":"https://api.github.com/repos/ClusterHQ/flocker/git/commits{/sha}","comments_url":"https://api.github.com/repos/ClusterHQ/flocker/comments{/number}","issue_comment_url":"https://api.github.com/repos/ClusterHQ/flocker/issues/comments{/number}","contents_url":"https://api.github.com/repos/ClusterHQ/flocker/contents/{+path}","compare_url":"https://api.github.com/repos/ClusterHQ/flocker/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ClusterHQ/flocker/merges","archive_url":"https://api.github.com/repos/ClusterHQ/flocker/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ClusterHQ/flocker/downloads","issues_url":"https://api.github.com/repos/ClusterHQ/flocker/issues{/number}","pulls_url":"https://api.github.com/repos/ClusterHQ/flocker/pulls{/number}","milestones_url":"https://api.github.com/repos/ClusterHQ/flocker/milestones{/number}","notifications_url":"https://api.github.com/repos/ClusterHQ/flocker/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ClusterHQ/flocker/labels{/name}","releases_url":"https://api.github.com/repos/ClusterHQ/flocker/releases{/id}","created_at":"2014-04-28T18:02:14Z","updated_at":"2015-08-25T22:05:01Z","pushed_at":"2015-08-26T13:45:44Z","git_url":"git://github.com/ClusterHQ/flocker.git","ssh_url":"git@github.com:ClusterHQ/flocker.git","clone_url":"https://github.com/ClusterHQ/flocker.git","svn_url":"https://github.com/ClusterHQ/flocker","homepage":"https://clusterhq.com","size":64020,"stargazers_count":1788,"watchers_count":1788,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":122,"mirror_url":null,"open_issues_count":26,"forks":122,"open_issues":26,"watchers":1788,"default_branch":"master"}},"base":{"label":"ClusterHQ:master","ref":"master","sha":"3f318c4d4033462668c796138db9985291581ee6","user":{"login":"ClusterHQ","id":7913449,"avatar_url":"https://avatars.githubusercontent.com/u/7913449?v=3","gravatar_id":"","url":"https://api.github.com/users/ClusterHQ","html_url":"https://github.com/ClusterHQ","followers_url":"https://api.github.com/users/ClusterHQ/followers","following_url":"https://api.github.com/users/ClusterHQ/following{/other_user}","gists_url":"https://api.github.com/users/ClusterHQ/gists{/gist_id}","starred_url":"https://api.github.com/users/ClusterHQ/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ClusterHQ/subscriptions","organizations_url":"https://api.github.com/users/ClusterHQ/orgs","repos_url":"https://api.github.com/users/ClusterHQ/repos","events_url":"https://api.github.com/users/ClusterHQ/events{/privacy}","received_events_url":"https://api.github.com/users/ClusterHQ/received_events","type":"Organization","site_admin":false},"repo":{"id":19248542,"name":"flocker","full_name":"ClusterHQ/flocker","owner":{"login":"ClusterHQ","id":7913449,"avatar_url":"https://avatars.githubusercontent.com/u/7913449?v=3","gravatar_id":"","url":"https://api.github.com/users/ClusterHQ","html_url":"https://github.com/ClusterHQ","followers_url":"https://api.github.com/users/ClusterHQ/followers","following_url":"https://api.github.com/users/ClusterHQ/following{/other_user}","gists_url":"https://api.github.com/users/ClusterHQ/gists{/gist_id}","starred_url":"https://api.github.com/users/ClusterHQ/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ClusterHQ/subscriptions","organizations_url":"https://api.github.com/users/ClusterHQ/orgs","repos_url":"https://api.github.com/users/ClusterHQ/repos","events_url":"https://api.github.com/users/ClusterHQ/events{/privacy}","received_events_url":"https://api.github.com/users/ClusterHQ/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/ClusterHQ/flocker","description":"Easily manage Docker containers & their data","fork":false,"url":"https://api.github.com/repos/ClusterHQ/flocker","forks_url":"https://api.github.com/repos/ClusterHQ/flocker/forks","keys_url":"https://api.github.com/repos/ClusterHQ/flocker/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ClusterHQ/flocker/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ClusterHQ/flocker/teams","hooks_url":"https://api.github.com/repos/ClusterHQ/flocker/hooks","issue_events_url":"https://api.github.com/repos/ClusterHQ/flocker/issues/events{/number}","events_url":"https://api.github.com/repos/ClusterHQ/flocker/events","assignees_url":"https://api.github.com/repos/ClusterHQ/flocker/assignees{/user}","branches_url":"https://api.github.com/repos/ClusterHQ/flocker/branches{/branch}","tags_url":"https://api.github.com/repos/ClusterHQ/flocker/tags","blobs_url":"https://api.github.com/repos/ClusterHQ/flocker/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ClusterHQ/flocker/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ClusterHQ/flocker/git/refs{/sha}","trees_url":"https://api.github.com/repos/ClusterHQ/flocker/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ClusterHQ/flocker/statuses/{sha}","languages_url":"https://api.github.com/repos/ClusterHQ/flocker/languages","stargazers_url":"https://api.github.com/repos/ClusterHQ/flocker/stargazers","contributors_url":"https://api.github.com/repos/ClusterHQ/flocker/contributors","subscribers_url":"https://api.github.com/repos/ClusterHQ/flocker/subscribers","subscription_url":"https://api.github.com/repos/ClusterHQ/flocker/subscription","commits_url":"https://api.github.com/repos/ClusterHQ/flocker/commits{/sha}","git_commits_url":"https://api.github.com/repos/ClusterHQ/flocker/git/commits{/sha}","comments_url":"https://api.github.com/repos/ClusterHQ/flocker/comments{/number}","issue_comment_url":"https://api.github.com/repos/ClusterHQ/flocker/issues/comments{/number}","contents_url":"https://api.github.com/repos/ClusterHQ/flocker/contents/{+path}","compare_url":"https://api.github.com/repos/ClusterHQ/flocker/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ClusterHQ/flocker/merges","archive_url":"https://api.github.com/repos/ClusterHQ/flocker/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ClusterHQ/flocker/downloads","issues_url":"https://api.github.com/repos/ClusterHQ/flocker/issues{/number}","pulls_url":"https://api.github.com/repos/ClusterHQ/flocker/pulls{/number}","milestones_url":"https://api.github.com/repos/ClusterHQ/flocker/milestones{/number}","notifications_url":"https://api.github.com/repos/ClusterHQ/flocker/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ClusterHQ/flocker/labels{/name}","releases_url":"https://api.github.com/repos/ClusterHQ/flocker/releases{/id}","created_at":"2014-04-28T18:02:14Z","updated_at":"2015-08-25T22:05:01Z","pushed_at":"2015-08-26T13:45:44Z","git_url":"git://github.com/ClusterHQ/flocker.git","ssh_url":"git@github.com:ClusterHQ/flocker.git","clone_url":"https://github.com/ClusterHQ/flocker.git","svn_url":"https://github.com/ClusterHQ/flocker","homepage":"https://clusterhq.com","size":64020,"stargazers_count":1788,"watchers_count":1788,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":122,"mirror_url":null,"open_issues_count":26,"forks":122,"open_issues":26,"watchers":1788,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/ClusterHQ/flocker/pulls/1886"},"html":{"href":"https://github.com/ClusterHQ/flocker/pull/1886"},"issue":{"href":"https://api.github.com/repos/ClusterHQ/flocker/issues/1886"},"comments":{"href":"https://api.github.com/repos/ClusterHQ/flocker/issues/1886/comments"},"review_comments":{"href":"https://api.github.com/repos/ClusterHQ/flocker/pulls/1886/comments"},"review_comment":{"href":"https://api.github.com/repos/ClusterHQ/flocker/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/ClusterHQ/flocker/pulls/1886/commits"},"statuses":{"href":"https://api.github.com/repos/ClusterHQ/flocker/statuses/7922e44cc1bc0d03a36ea8933f4cbf6b32c44de6"}}}}