Review template rendering, and release authoring-related docs

[bgandon]

Hello Bosh mates,

This is a big PR after a large review of several pieces of docs related to release development. As a release author and as a trainer (facing the trainees legitimate “surprise” when reading the Bosh docs), I wanted to complete and update these for years, so I’m glad I can contribute something today.

Individual commits are breaking the changes into smaller consistent chunks. This might ease the review.

I’ve went quite far in documenting the spec object in the evaluation context for ERB templates. In fact, many exposed properties should not be there at all. We can discuss which ones, and I can submit a PR for that refactoring in bosh core.

I’ve also added a “caveat” about the obviously missing spec.job_name property, that would be very useful for release authors, even though not strictly necessary. Indeed, that would allow writing ERB snippets that can just be used with pure copy/paste, no editing, and that would be cool. Being cool does matter.

Cheers

[ystros]

Thanks for these docs updates! In addition to the more thorough field documentation for templates and spec files, I like the emphasis of moving folks to use BPM instead of using control scripts.

I spotted several typos; I may not have spotted everything, so it may be good to run these pages through a spell checker. Otherwise, looks good overall!

[bgandon]

Thanks for the review @ystros 👍 Unfortunately didn’t see your comments until now, but will fix the typos soon!

[bgandon]

Thanks @ystros I’ fixed the typos.

Please note that my last two commit have introduced new remarks

• use_dns_addresses is actually enabled on most installations: https://github.com/cloudfoundry/docs-bosh/pull/813/files#diff-574863497b2c11de0dc55cfd61066c5171d4cb1942923c121b7113ad558b7c85R356-R362
• There is a special trick for obtaining the default network name within ERB templates, that is rather complex to get right: https://github.com/cloudfoundry/docs-bosh/pull/813/files#diff-383b304a5554579508be10bbf49a5dc2527f1c07d02540f9613509852054f81cR363-R381

Thanks for reviewing these two additions!

[ystros]

Thanks for the updates! Documenting how to get network names via our unusual coupling with OpenStruct makes me nervous (making it a de-facto supported mechanism), but it accurately reflects reality right now. The docs can be updated later if we ever change that coupling or provide a better mechanism for getting network names.

lgtm!

[beyhan]

Thanks @bgandon!