{"action":"created","comment":{"url":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/comments/53219973","id":53219973,"diff_hunk":"@@ -0,0 +1,664 @@\n+﻿# Helm-DM Charts Proposal\n+\n+\n+This document contains a proposal for a new Chart format that both Helm and DM would standardize upon as Helm becomes a DM client.\n+\n+\n+* [Changes](#changes)\n+* [tl;dr: Summary](#tldr-summary)\n+* [Goals](#goals)\n+  * [Non-Goals](#non-goals)\n+* [The Chart Format](#the-chart-format)\n+  * [Directory Layout](#directory-layout)\n+  * [Generators and Templates](#generators-and-templates)\n+    * [The Generator Header](#the-generator-header)\n+    * [Python/Jinja Templates (aka DM Templates)](#pythonjinja-templates-aka-dm-templates)\n+    * [Go Templates (formerly Helm Templates)](#go-templates-formerly-helm-templates)\n+  * [The Chart File](#the-chart-file)\n+    * [Dependency Information](#dependency-information)\n+  * [Releasing a Chart](#releasing-a-chart)\n+* [The Chart Repository](#the-chart-repository)\n+  * [The Provenance File](#the-provenance-file)\n+  * [Repository Protocol](#repository-protocol)\n+  * [Aside: Why a Flat Repository Namespace?](#aside-why-a-flat-repository-namespace)\n+  * [Aside: Why Not Git(Hub) or VCS?](#aside-why-not-github-or-vcs)\n+* [Chart References: Long form, short form, and local reference](#chart-references-long-form-short-form-and-local-reference)\n+  * [Long Form](#long-form)\n+  * [Short Form](#short-form)\n+  * [Local References](#local-references)\n+* [Appendix A: User Stories for Charts](#appendix-a-user-stories-for-charts)\n+* [Appendix B: The Standard Chart Repository](#appendix-b-the-standard-chart-repository)\n+* [Appendix C: EBNF for Generate Header](#appendix-c-ebnf-for-generate-header)\n+* [Appendix D: References](#appendix-d-references)\n+\n+\n+## Changes\n+\n+| Date        | Author        | Changes                                                |\n+| ------------|:-------------:|:-------------------------------------------------------|\n+| 2016-01-21  | mbutcher@deis | Added manifests/ to chart.                             |\n+| 2016-01-25  | mbutcher@deis | Added clarifications based on comments.                |\n+| 2016-01-26  | mbutcher@deis | Added hook/, removed manifests/. Added generate header.|\n+\n+\n+## tl;dr: Summary\n+* A **Chart** is a folder or archive containing a _Chart.yaml_ file, a _templates/_ directory with one or more template files and supporting files, such as schemas and UI directives, and optionally a _README.md_ and _LICENSE_ file.\n+* When a chart is **released**, it is tested, versioned, provenanced, and loaded into a chart repository.\n+* A **Chart Repository** is organized according to the conventions of object storage. It is accessible by combining a domain with a repository ID (bucket), and can be browsed. A chart repository contains one or more versioned charts.\n+* There are three ways to reference charts. A **local reference** references a chart by relative or absolute file system path. It is intended for development. A **long name**, or fully qualified URL, refers to a released chart (in a chart repository) by URL. A **short name**, or mnemonic, is a shortened reference to a chart in a chart repository. A short name can be converted to a **long name** deterministically, and can therefore be used anywhere a long name can be used.\n+\n+## Goals\n+The goal of this proposal is to define the following aspects of Helm-DM charts:\n+\n+\n+* The **format of a Chart**\n+* The **layout of a Chart repository**, with recommendations about implementations\n+* The format of a **short name** (mnemonic name) of a chart, as well as its fully qualified **long name**, and conventions for referencing local charts instead of short/long names.\n+\n+\n+We assume that we are developing a technology that will enjoy widespread use among developers and operators who…\n+\n+\n+* Are familiar with general Kubernetes design\n+* Are capable of reading and writing high-level formats like JSON, YAML, and maybe shell scripts\n+* Have low tolerance for complexity, and are not willing to become domain experts, but…\n+* Advanced users may be interested in, and willing to, learn advanced features to build much more interesting charts\n+\n+\n+Based on these, our design goal is to make it **easy to find, use, author, release, and maintain charts**, while still making it possible for advanced users to build sophisticated charts. Furthermore, we have begun the process of **attaching provenance to charts**.\n+\n+\n+We have attempted to build a proposal that does not lose any of the functionality of DM, and which loses only Helm functionality that we believe is disposable. But both tools will need to change substantial portions of their chart-handling logic.\n+### Non-Goals\n+This proposal doesn’t define how either the client or the server must use this data, though we make some non-normative recommendations (e.g. “this data may be displayed to the user” or “a suitable backend will be able to translate this to a fully qualified URL”).\n+\n+\n+Consequently, this document does not describe the implementation of either client or server sides of this spec. While it defines the pieces necessary for developing and deploying a chart, it does not define a development workflow. Some considerations are listed in [Appendix B](#appendix-b-the-standard-chart-repository).\n+\n+\n+## The Chart Format\n+Borrowing the nomenclature from Helm, we define a Chart as a bundle of data and metadata whose contents are sufficient for installing a workload into a Kubernetes cluster running DM.\n+\n+\n+A Chart is composed of the following pieces:\n+\n+\n+1. A human- and machine-readable metadata file called `Chart.yaml`\n+2. A directory named `templates/`\n+3. An optional `README.md` file\n+4. An optional `LICENSE` file\n+5. An optional `docs/` directory\n+6. An optional `hooks/` directory\n+7. An optional `icon.svg.`\n+\n+\n+A chart _may_ have other directories and files, but such files are not defined by or required by this proposal. For the purposes of this proposal, any additional files do not contribute to the core functionality of chart installation.\n+\n+\n+_Note: When a chart file is deployed, a [provenance file](#the-provenance-file) is generated for the chart. That file is not stored inside of the chart, but is considered part of the chart’s packaged format._\n+\n+\n+The chart.yaml file format is described [later in this document](#the-chart-file).\n+\n+\n+The `templates/` directory contains one or more template files, as defined in the [Directory Layout](#directory-layout) section. Templates, along with all of their supporting files, are located therein.\n+\n+\n+An optional `README.md` file may be specified, which contains long-form text information about using this chart. Tools may display this information, if present. The README.md file is in Markdown format, and should contain information about a Chart’s purpose, usage, and development.\n+\n+\n+An optional `LICENSE` file may be present, which specifies license information for this chart and/or the images dependent on it.\n+\n+\n+An optional `docs/` directory may be present, and may contain one or more documentation files. This directory contains documentation that is more specific, verbose, or thorough than what is present in the `README.md` file.\n+\n+\n+An optional `hooks/` directory may be present. **This is reserved for future use.** A deployment engine may specify lifecycle hooks, such as `pre-install`, `pre-render`, `post-install` and `post-render`. Lifecycle hooks provide an opportunity for a chart author to run additional steps in the processing pipeline. Implementations of these hooks are stored here. _No other files may be stored in this directory._","path":"docs/design/chart_format.md","position":116,"original_position":116,"commit_id":"9228e772f60f88c2fa5a55cd561599c6fc664bab","original_commit_id":"cf43dcf44ad8bb98fc1914150503a9c4cb1f5855","user":{"login":"jackgr","id":5607565,"avatar_url":"https://avatars.githubusercontent.com/u/5607565?v=3","gravatar_id":"","url":"https://api.github.com/users/jackgr","html_url":"https://github.com/jackgr","followers_url":"https://api.github.com/users/jackgr/followers","following_url":"https://api.github.com/users/jackgr/following{/other_user}","gists_url":"https://api.github.com/users/jackgr/gists{/gist_id}","starred_url":"https://api.github.com/users/jackgr/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jackgr/subscriptions","organizations_url":"https://api.github.com/users/jackgr/orgs","repos_url":"https://api.github.com/users/jackgr/repos","events_url":"https://api.github.com/users/jackgr/events{/privacy}","received_events_url":"https://api.github.com/users/jackgr/received_events","type":"User","site_admin":false},"body":"Perfect. Thanks.","created_at":"2016-02-17T19:46:18Z","updated_at":"2016-02-17T19:46:18Z","html_url":"https://github.com/kubernetes/deployment-manager/pull/250#discussion_r53219973","pull_request_url":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/250","_links":{"self":{"href":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/comments/53219973"},"html":{"href":"https://github.com/kubernetes/deployment-manager/pull/250#discussion_r53219973"},"pull_request":{"href":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/250"}}},"pull_request":{"url":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/250","id":58844793,"html_url":"https://github.com/kubernetes/deployment-manager/pull/250","diff_url":"https://github.com/kubernetes/deployment-manager/pull/250.diff","patch_url":"https://github.com/kubernetes/deployment-manager/pull/250.patch","issue_url":"https://api.github.com/repos/kubernetes/deployment-manager/issues/250","number":250,"state":"open","locked":false,"title":"add helm-dm charts proposal to dm docs","user":{"login":"michelleN","id":1497123,"avatar_url":"https://avatars.githubusercontent.com/u/1497123?v=3","gravatar_id":"","url":"https://api.github.com/users/michelleN","html_url":"https://github.com/michelleN","followers_url":"https://api.github.com/users/michelleN/followers","following_url":"https://api.github.com/users/michelleN/following{/other_user}","gists_url":"https://api.github.com/users/michelleN/gists{/gist_id}","starred_url":"https://api.github.com/users/michelleN/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/michelleN/subscriptions","organizations_url":"https://api.github.com/users/michelleN/orgs","repos_url":"https://api.github.com/users/michelleN/repos","events_url":"https://api.github.com/users/michelleN/events{/privacy}","received_events_url":"https://api.github.com/users/michelleN/received_events","type":"User","site_admin":false},"body":"The is the markdown version of the helm-dm chart proposal.","created_at":"2016-02-10T03:50:46Z","updated_at":"2016-02-17T19:46:18Z","closed_at":null,"merged_at":null,"merge_commit_sha":"6f403942bfadcb3c9ed54777ea8a1b4a642c0034","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/250/commits","review_comments_url":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/250/comments","review_comment_url":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/comments{/number}","comments_url":"https://api.github.com/repos/kubernetes/deployment-manager/issues/250/comments","statuses_url":"https://api.github.com/repos/kubernetes/deployment-manager/statuses/9228e772f60f88c2fa5a55cd561599c6fc664bab","head":{"label":"michelleN:chartdoc","ref":"chartdoc","sha":"9228e772f60f88c2fa5a55cd561599c6fc664bab","user":{"login":"michelleN","id":1497123,"avatar_url":"https://avatars.githubusercontent.com/u/1497123?v=3","gravatar_id":"","url":"https://api.github.com/users/michelleN","html_url":"https://github.com/michelleN","followers_url":"https://api.github.com/users/michelleN/followers","following_url":"https://api.github.com/users/michelleN/following{/other_user}","gists_url":"https://api.github.com/users/michelleN/gists{/gist_id}","starred_url":"https://api.github.com/users/michelleN/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/michelleN/subscriptions","organizations_url":"https://api.github.com/users/michelleN/orgs","repos_url":"https://api.github.com/users/michelleN/repos","events_url":"https://api.github.com/users/michelleN/events{/privacy}","received_events_url":"https://api.github.com/users/michelleN/received_events","type":"User","site_admin":false},"repo":{"id":50368543,"name":"deployment-manager","full_name":"michelleN/deployment-manager","owner":{"login":"michelleN","id":1497123,"avatar_url":"https://avatars.githubusercontent.com/u/1497123?v=3","gravatar_id":"","url":"https://api.github.com/users/michelleN","html_url":"https://github.com/michelleN","followers_url":"https://api.github.com/users/michelleN/followers","following_url":"https://api.github.com/users/michelleN/following{/other_user}","gists_url":"https://api.github.com/users/michelleN/gists{/gist_id}","starred_url":"https://api.github.com/users/michelleN/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/michelleN/subscriptions","organizations_url":"https://api.github.com/users/michelleN/orgs","repos_url":"https://api.github.com/users/michelleN/repos","events_url":"https://api.github.com/users/michelleN/events{/privacy}","received_events_url":"https://api.github.com/users/michelleN/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/michelleN/deployment-manager","description":"Deployment Manager on Kubernetes","fork":true,"url":"https://api.github.com/repos/michelleN/deployment-manager","forks_url":"https://api.github.com/repos/michelleN/deployment-manager/forks","keys_url":"https://api.github.com/repos/michelleN/deployment-manager/keys{/key_id}","collaborators_url":"https://api.github.com/repos/michelleN/deployment-manager/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/michelleN/deployment-manager/teams","hooks_url":"https://api.github.com/repos/michelleN/deployment-manager/hooks","issue_events_url":"https://api.github.com/repos/michelleN/deployment-manager/issues/events{/number}","events_url":"https://api.github.com/repos/michelleN/deployment-manager/events","assignees_url":"https://api.github.com/repos/michelleN/deployment-manager/assignees{/user}","branches_url":"https://api.github.com/repos/michelleN/deployment-manager/branches{/branch}","tags_url":"https://api.github.com/repos/michelleN/deployment-manager/tags","blobs_url":"https://api.github.com/repos/michelleN/deployment-manager/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/michelleN/deployment-manager/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/michelleN/deployment-manager/git/refs{/sha}","trees_url":"https://api.github.com/repos/michelleN/deployment-manager/git/trees{/sha}","statuses_url":"https://api.github.com/repos/michelleN/deployment-manager/statuses/{sha}","languages_url":"https://api.github.com/repos/michelleN/deployment-manager/languages","stargazers_url":"https://api.github.com/repos/michelleN/deployment-manager/stargazers","contributors_url":"https://api.github.com/repos/michelleN/deployment-manager/contributors","subscribers_url":"https://api.github.com/repos/michelleN/deployment-manager/subscribers","subscription_url":"https://api.github.com/repos/michelleN/deployment-manager/subscription","commits_url":"https://api.github.com/repos/michelleN/deployment-manager/commits{/sha}","git_commits_url":"https://api.github.com/repos/michelleN/deployment-manager/git/commits{/sha}","comments_url":"https://api.github.com/repos/michelleN/deployment-manager/comments{/number}","issue_comment_url":"https://api.github.com/repos/michelleN/deployment-manager/issues/comments{/number}","contents_url":"https://api.github.com/repos/michelleN/deployment-manager/contents/{+path}","compare_url":"https://api.github.com/repos/michelleN/deployment-manager/compare/{base}...{head}","merges_url":"https://api.github.com/repos/michelleN/deployment-manager/merges","archive_url":"https://api.github.com/repos/michelleN/deployment-manager/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/michelleN/deployment-manager/downloads","issues_url":"https://api.github.com/repos/michelleN/deployment-manager/issues{/number}","pulls_url":"https://api.github.com/repos/michelleN/deployment-manager/pulls{/number}","milestones_url":"https://api.github.com/repos/michelleN/deployment-manager/milestones{/number}","notifications_url":"https://api.github.com/repos/michelleN/deployment-manager/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/michelleN/deployment-manager/labels{/name}","releases_url":"https://api.github.com/repos/michelleN/deployment-manager/releases{/id}","deployments_url":"https://api.github.com/repos/michelleN/deployment-manager/deployments","created_at":"2016-01-25T17:39:42Z","updated_at":"2016-01-25T17:39:43Z","pushed_at":"2016-02-17T18:18:01Z","git_url":"git://github.com/michelleN/deployment-manager.git","ssh_url":"git@github.com:michelleN/deployment-manager.git","clone_url":"https://github.com/michelleN/deployment-manager.git","svn_url":"https://github.com/michelleN/deployment-manager","homepage":null,"size":617,"stargazers_count":0,"watchers_count":0,"language":"Go","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"kubernetes:master","ref":"master","sha":"476e71f5d349fce3ff703057dea511f7c568865c","user":{"login":"kubernetes","id":13629408,"avatar_url":"https://avatars.githubusercontent.com/u/13629408?v=3","gravatar_id":"","url":"https://api.github.com/users/kubernetes","html_url":"https://github.com/kubernetes","followers_url":"https://api.github.com/users/kubernetes/followers","following_url":"https://api.github.com/users/kubernetes/following{/other_user}","gists_url":"https://api.github.com/users/kubernetes/gists{/gist_id}","starred_url":"https://api.github.com/users/kubernetes/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kubernetes/subscriptions","organizations_url":"https://api.github.com/users/kubernetes/orgs","repos_url":"https://api.github.com/users/kubernetes/repos","events_url":"https://api.github.com/users/kubernetes/events{/privacy}","received_events_url":"https://api.github.com/users/kubernetes/received_events","type":"Organization","site_admin":false},"repo":{"id":43723161,"name":"deployment-manager","full_name":"kubernetes/deployment-manager","owner":{"login":"kubernetes","id":13629408,"avatar_url":"https://avatars.githubusercontent.com/u/13629408?v=3","gravatar_id":"","url":"https://api.github.com/users/kubernetes","html_url":"https://github.com/kubernetes","followers_url":"https://api.github.com/users/kubernetes/followers","following_url":"https://api.github.com/users/kubernetes/following{/other_user}","gists_url":"https://api.github.com/users/kubernetes/gists{/gist_id}","starred_url":"https://api.github.com/users/kubernetes/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kubernetes/subscriptions","organizations_url":"https://api.github.com/users/kubernetes/orgs","repos_url":"https://api.github.com/users/kubernetes/repos","events_url":"https://api.github.com/users/kubernetes/events{/privacy}","received_events_url":"https://api.github.com/users/kubernetes/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/kubernetes/deployment-manager","description":"Deployment Manager on Kubernetes","fork":false,"url":"https://api.github.com/repos/kubernetes/deployment-manager","forks_url":"https://api.github.com/repos/kubernetes/deployment-manager/forks","keys_url":"https://api.github.com/repos/kubernetes/deployment-manager/keys{/key_id}","collaborators_url":"https://api.github.com/repos/kubernetes/deployment-manager/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/kubernetes/deployment-manager/teams","hooks_url":"https://api.github.com/repos/kubernetes/deployment-manager/hooks","issue_events_url":"https://api.github.com/repos/kubernetes/deployment-manager/issues/events{/number}","events_url":"https://api.github.com/repos/kubernetes/deployment-manager/events","assignees_url":"https://api.github.com/repos/kubernetes/deployment-manager/assignees{/user}","branches_url":"https://api.github.com/repos/kubernetes/deployment-manager/branches{/branch}","tags_url":"https://api.github.com/repos/kubernetes/deployment-manager/tags","blobs_url":"https://api.github.com/repos/kubernetes/deployment-manager/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/kubernetes/deployment-manager/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/kubernetes/deployment-manager/git/refs{/sha}","trees_url":"https://api.github.com/repos/kubernetes/deployment-manager/git/trees{/sha}","statuses_url":"https://api.github.com/repos/kubernetes/deployment-manager/statuses/{sha}","languages_url":"https://api.github.com/repos/kubernetes/deployment-manager/languages","stargazers_url":"https://api.github.com/repos/kubernetes/deployment-manager/stargazers","contributors_url":"https://api.github.com/repos/kubernetes/deployment-manager/contributors","subscribers_url":"https://api.github.com/repos/kubernetes/deployment-manager/subscribers","subscription_url":"https://api.github.com/repos/kubernetes/deployment-manager/subscription","commits_url":"https://api.github.com/repos/kubernetes/deployment-manager/commits{/sha}","git_commits_url":"https://api.github.com/repos/kubernetes/deployment-manager/git/commits{/sha}","comments_url":"https://api.github.com/repos/kubernetes/deployment-manager/comments{/number}","issue_comment_url":"https://api.github.com/repos/kubernetes/deployment-manager/issues/comments{/number}","contents_url":"https://api.github.com/repos/kubernetes/deployment-manager/contents/{+path}","compare_url":"https://api.github.com/repos/kubernetes/deployment-manager/compare/{base}...{head}","merges_url":"https://api.github.com/repos/kubernetes/deployment-manager/merges","archive_url":"https://api.github.com/repos/kubernetes/deployment-manager/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/kubernetes/deployment-manager/downloads","issues_url":"https://api.github.com/repos/kubernetes/deployment-manager/issues{/number}","pulls_url":"https://api.github.com/repos/kubernetes/deployment-manager/pulls{/number}","milestones_url":"https://api.github.com/repos/kubernetes/deployment-manager/milestones{/number}","notifications_url":"https://api.github.com/repos/kubernetes/deployment-manager/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/kubernetes/deployment-manager/labels{/name}","releases_url":"https://api.github.com/repos/kubernetes/deployment-manager/releases{/id}","deployments_url":"https://api.github.com/repos/kubernetes/deployment-manager/deployments","created_at":"2015-10-06T01:07:32Z","updated_at":"2016-02-16T05:10:13Z","pushed_at":"2016-02-17T18:18:01Z","git_url":"git://github.com/kubernetes/deployment-manager.git","ssh_url":"git@github.com:kubernetes/deployment-manager.git","clone_url":"https://github.com/kubernetes/deployment-manager.git","svn_url":"https://github.com/kubernetes/deployment-manager","homepage":null,"size":5926,"stargazers_count":80,"watchers_count":80,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":30,"mirror_url":null,"open_issues_count":72,"forks":30,"open_issues":72,"watchers":80,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/250"},"html":{"href":"https://github.com/kubernetes/deployment-manager/pull/250"},"issue":{"href":"https://api.github.com/repos/kubernetes/deployment-manager/issues/250"},"comments":{"href":"https://api.github.com/repos/kubernetes/deployment-manager/issues/250/comments"},"review_comments":{"href":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/250/comments"},"review_comment":{"href":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/kubernetes/deployment-manager/pulls/250/commits"},"statuses":{"href":"https://api.github.com/repos/kubernetes/deployment-manager/statuses/9228e772f60f88c2fa5a55cd561599c6fc664bab"}}}}