Add simplestreams doc

Add simplestreams doc

Add simplestreams-metadata.txt to describe
how juju uses simplestreams image and tools
metadata

https://code.launchpad.net/~wallyworld/juju-core/simplestreams-doc/+merge/193542

(do not edit description out of merge proposal)

[wallyworld, 2013-11-01 05:00:43]

Please take a look.

[wallyworld, 2013-11-03 23:33:19]

Please take a look.

[john2, 2013-11-04 13:58:52]

LGTM.

I have some comments but I'd rather land it than not.

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
File doc/simplestreams-metadata.txt (right):

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:9: simplestreams is used to describe related
items in a structural fashion. See the
"Simplestreams" for the start of a sentence?

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:28: Metadata may be inline signed, or unsigned.
By convention, signed json metadata files have
"By convention" seems like it would allow you to name it something else, but I'm
pretty sure it has to be named sjson or we don't validate it. Is that true?

So I would put: We indicate a metadata file is signed by using the '.sjson'
extension.

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:57: |_ product-bar.(s)json
You indenting here is a little inconsistent |_streams vs |_ index.json
I was also slightly confused if the '_' was part of the value.

I don't know if it would look better as:

|- streams or with the _ but we probably want to make sure to have a blank space
at each level.

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:60: match whatever is in the index file.
I have the feeling this is more confusing than helpful. (I don't think people
would benefit by calling it product-foo.html, for example :).

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:66: The produc id is formed as follows:
typo "product"

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:76: |_streams
Similar prefix fixes.

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:101: These are specified in the environments.yaml
file. For images, use "images-url";
Do we need to distinguish that they end up in the .jenv file?

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:137: and visa versa.
vice versa

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:167: usually just the image metadata is required
to be created.
This sentence is a bit awkward.
I would probably do:
Juju tools exist to help with generating and validating image and tools
metadata. For tools, it is often easiest to just mirror
https://streams.canonical.com/tools. However image metadata cannot be simply
mirrored because the image ids are taken from the cloud storage provider.

[wallyworld, 2013-11-05 02:02:01]

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
File doc/simplestreams-metadata.txt (right):

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:9: simplestreams is used to describe related
items in a structural fashion. See the
On 2013/11/04 13:58:52, john2 wrote:
> "Simplestreams" for the start of a sentence?

Done.

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:28: Metadata may be inline signed, or unsigned.
By convention, signed json metadata files have
On 2013/11/04 13:58:52, john2 wrote:
> "By convention" seems like it would allow you to name it something else, but
I'm
> pretty sure it has to be named sjson or we don't validate it. Is that true?
> 
> So I would put: We indicate a metadata file is signed by using the '.sjson'
> extension.
> 

Done.

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:57: |_ product-bar.(s)json
On 2013/11/04 13:58:52, john2 wrote:
> You indenting here is a little inconsistent |_streams vs |_ index.json
> I was also slightly confused if the '_' was part of the value.
> 
> I don't know if it would look better as:
> 
> |- streams or with the _ but we probably want to make sure to have a blank
space
> at each level.

I used |-

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:60: match whatever is in the index file.
On 2013/11/04 13:58:52, john2 wrote:
> I have the feeling this is more confusing than helpful. (I don't think people
> would benefit by calling it product-foo.html, for example :).
> 

I've reworded, but it is important. The index file contains paths and each path
value must point to a product file. Unlike the name of the index file, which is
fixed, the product files can be called anything, so long as they match the path
values in the index file.

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:66: The produc id is formed as follows:
On 2013/11/04 13:58:52, john2 wrote:
> typo "product"

Done.

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:101: These are specified in the environments.yaml
file. For images, use "images-url";
On 2013/11/04 13:58:52, john2 wrote:
> Do we need to distinguish that they end up in the .jenv file?

Done.

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:137: and visa versa.
On 2013/11/04 13:58:52, john2 wrote:
> vice versa

Done.

https://codereview.appspot.com/20730043/diff/20001/doc/simplestreams-metadata...
doc/simplestreams-metadata.txt:167: usually just the image metadata is required
to be created.
On 2013/11/04 13:58:52, john2 wrote:
> This sentence is a bit awkward.
> I would probably do:
> Juju tools exist to help with generating and validating image and tools
> metadata. For tools, it is often easiest to just mirror
> https://streams.canonical.com/tools. However image metadata cannot be simply
> mirrored because the image ids are taken from the cloud storage provider.

Done.