Open Stack

On 19/05/17 11:00, Lance Haig wrote:
> Hi,
>
> As we know the heat-templates repository has become out of date in some
> respects and also has been difficult to be maintained from a community
> perspective.
>
> For me the repository is quiet confusing with different styles that are
> used to show certain aspects and other styles for older template examples.
>
> This I think leads to confusion and perhaps many people who give up on
> heat as a resource as things are not that clear.
>
> From discussions in other threads and on the IRC channel I have seen
> that there is a need to change things a bit.
>
>
> This is why I would like to start the discussion that we rethink the
> template example repository.
>
> I would like to open the discussion with mys suggestions.
>
>   * We need to differentiate templates that work on earlier versions of
>     heat that what is the current supported versions.

I typically use the heat_template_version for this. Technically this is 
entirely independent of what resource types are available in Heat. 
Nevertheless, if I submit e.g. a template that uses new resources only 
available in Ocata, I'll set 'heat_template_version: ocata' even if the 
template doesn't contain any Ocata-only intrinsic functions. We could 
make that a convention.

>       o I have suggested that we create directories that relate to
>         different versions so that you can create a stable version of
>         examples for the heat version and they should always remain
>         stable for that version and once it goes out of support can
>         remain there.

I'm reluctant to move existing things around unless its absolutely 
necessary, because there are a lot of links out in the wild to templates 
that will break. And they're links directly to the Git repo, it's not 
like we publish them somewhere and could add redirects.

Although that gives me an idea: what if we published them somewhere? We 
could make templates actually discoverable by publishing a list of 
descriptions (instead of just the names like you get through browsing 
the Git repo). And we could even add some metadata to indicate what 
versions of Heat they run on.

>       o This would mean people can find their version of heat and know
>         these templates all work on their version

This would mean keeping multiple copies of each template and maintaining 
them all. I don't think this is the right way to do this - to maintain 
old stuff what you need is a stable branch. That's also how you're going 
to be able to test against old versions of OpenStack in the gate.

As I suggested in the other thread, I'd be OK with moving deprecated 
stuff to a 'deprecated' directory and then eventually deleting it. 
Stable branches would then correctly reflect the status of those 
templates at each previous release.

>   * We should consider adding a docs section that that includes training
>     for new users.
>       o I know that there are documents hosted in the developer area and
>         these could be utilized but I would think having a documentation
>         section in the repository would be a good way to keep the
>         examples and the documents in the same place.
>       o This docs directory could also host some training for new users
>         and old ones on new features etc.. In a similar line to what is
>         here in this repo https://github.com/heat-extras/heat-tutorial
>   * We should include examples form the default hooks e.g. ansible salt
>     etc... with SoftwareDeployments.
>       o We found this quiet helpful for new users to understand what is
>         possible.
>   * We should make sure that the validation running against the
>     templates runs without ignoring errors.
>       o This was noted in IRC that some errors were ignored as the
>         endpoints or catalog was not available. It would be good to have
>         some form of headless catalog server that tests can be run
>         against so that developers of templates can validate before
>         submitting patches.

+1 to all of this.

> These points are here to open the discussions around this topic
>
> Please feel free to make your suggestions.

Thanks for kicking this off!

cheers,
Zane.