Printing readme after install

[jchauncey]

Given the following install

╰─○ helm install elasticsearch-logging
---> Running `kubectl create -f` ...
services/elasticsearch-logging
services/kibana-logging
replicationcontrollers/elasticsearch-logging-v1
replicationcontrollers/kibana-logging-v1
---> Done
========================================
# Elastic Search logging

## Description
This chart provides 3 distinct components - fluentd, elastic search, and kibana. Fluentd is used to ship logs from each node of the cluster to elastic search. Kibana is used to create sophisticated dashboards to find anomalies within the cluster.

## Elastic Search

## Kibana

## Fluentd
========================================

I think it would be best if we didnt print the readme. The readme should be something people can actually glean information from on how the chart works and the components it installs. Instead I think we should print the details block or the description in Chart.yaml.

[technosophos]

Maybe README wasn't the best name to give the file. Let's figure out a good alternative.

What this file was supposed to be is documented here:

https://github.com/helm/helm/blob/master/docs/awsome.md#the-readmemd-file

Essentially, it's supposed to tell you what to do now that the chart is installed. It's supposed to be like the caveats section of a Homebrew formula:

https://github.com/Homebrew/homebrew/blob/8c6777b2b8e847d5f2b447eae532fa8ecffa6467/Library/Formula/postgres-xc.rb#L109

Since we couldn't allow arbitrarily formatted data inside of the Chart.yaml file, we opted to put it in a different file.

What are some of the ways we could accomplish the same thing in a clearer way (without burdening the chart developer too much)?

[jchauncey]

Id like to see readme's be the documentation on how the charts work. What components they install, what images they use, environment variables, etc... Just like any readme would be for a repo.

In Glide.yaml there should be 1 field that is used to provide a short description of the chart and the installed components. That is what is printed out when you do a helm install.

Like this - This chart provides 3 distinct components - fluentd, elastic search, and kibana. Fluentd is used to ship logs from each node of the cluster to elastic search. Kibana is used to create sophisticated dashboards to find anomalies within the cluster.

[technosophos]

But what does printing the description of the project give you after you've installed it? What is more likely relevant is how you connect to or use the thing you just installed. The Selenium chart is a great example of this:

https://github.com/helm/charts/blob/master/selenium/README.md

[jchauncey]

Yeah I agree but that could be a lot of text. I just wonder if printing it out is a good thing. And because we call it README.md people will put markdown in it which will make it look funny in the console.

[technosophos]

Secretly, I was planning on reading the MD and converting it to neat-o console output, like headers being bolded and backticks being underlined and things like that.

[jchauncey]

The more I worked with helm yesterday I think the details section should be the what's next section. Not like a man page but just how you interact with the components installed. The readme should be left for more detailed information.

[technosophos]

@jchauncey would you mind mocking up a chartfile for discussion here? I'd like to get this on the 0.3 milestone.

[jchauncey]

name: elasticsearch-logging
home: https://github.com/elastic/elasticsearch
version: 0.1.0
description: Elastic Search + Kibana + fluentd = k8s logging
maintainers:
  -  <jchauncey@deis.com>
details:
  This chart provides 3 distinct components - fluentd, elastic search, and kibana. Fluentd is used to ship logs from each node of the cluster to elastic search. Kibana is used to create sophisticated dashboards to find anomalies within the cluster.

[technosophos]

How would we handle more complex install notes like this one?

https://github.com/helm/charts/blob/master/selenium/README.md

[jchauncey]

I think that stuff should be in the readme. You could totally add a bit of that info into the details section. But I would caution of doing too much.

[jchauncey]

name: selenium
home: http://www.seleniumhq.org 
version: 2.47.1
description: Selenium is a suite of tools to automate web browsers across many platforms.
maintainers:
- Elson Rodriguez <elson.rodriguez@gmail.com>
details:
This Chart deploys a scalable [Selnium Grid](http://www.seleniumhq.org) to your Kubernetes cluster using the official Selenium [Docker images](https://github.com/SeleniumHQ/docker-selenium). It creates 2 replication controllers - 1 for firefox and 1 for chrome.

To scale a browser you can issue the following command:
kubectl scale rc selenium-node-firefox --replicas=10
kubectl scale rc selenium-node-chrome --replicas=10

[prydonius]

We've found that printing README.md is a problem for us, as we expected this to contain information about how you would start off using the chart. For example, we were originally describing how you would fetch, generate and install the chart as we think this is useful when you're browsing through the charts repository - however, we removed this as it was too much information when it was printed out after installation.

I think printing out short usage notes (on configuration, how to access the application, etc.) is very useful, but it doesn't exist in the README.md. Instead of moving it to the Chart.yaml, I think a USAGE.md file would make more sense. This file could also interpolate from the environment, so we could display ports and other configuration settings.

@technosophos prettifying markdown would be cool, but for now it may just be better to use plain text.

[technosophos]

I think we will switch back to plain text for that file. Some possible name candidates that have been tossed around:

• USAGE.txt
• POSTINSTALL.txt
• CONFIG.txt

Any others? We'll pick one and add support for it.

[prydonius]

I actually really like POSTINSTALL.txt because it dedicates the file to this use-case. USAGE.txt could cause people to run into the same problem today with READMEs.