suggested (not enforced) order for Cask stanzas

[rolandwalker]

References: #4914

This is mostly documentation, but it also changes the template used by
brew cask create.

Based on the suggestions from @vitorgalvao in #4914 — but I went one farther
(since I like whitespace) and added another blank line before the start of the
artifacts "section" of the Cask.

Comments welcomed.

[vitorgalvao]

Looks good. I’ve modified #4910 (both the files and the description) accordingly, to reflect the extra blank line.

[tapeinosyne]

The new formatting seems sensible: even if the simplest casks may not benefit, grouping will become increasingly desirable as we add stanzas.

If we feel like considering different grouping strategies, I would suggest to conjoin url with version and sha256, since they all pertain to the distributed package. The homepage stanza is an addendum that can be useful to the user, but it is not part of the cask installation/uninstallation process.

Per contra, I am not sure if the number of purely informational stanzas would be sufficient to justify an isolated section. Besides homepage, I can think of the proposed license (included in #4688) and, perhaps, developer, but would these be mandatory?

[vitorgalvao]

I would suggest to conjoin url with version and sha256, since they all pertain to the distributed package.

I think they should be separate, since the grouping is also meant to differentiate stanzas that need to be changed more often. By reusing version, url should not need to be messed with for quite some time, like home.

[tapeinosyne]

Yes, it is a different perspective. I would personally favor grouping by purpose rather than according to a "edit heatmap". (I don't feel strongly either way.)

Let us summon @caskroom/maintainers for more opinions. Edit: @caskroom/maintainers seems to be forbidden magicks for me.

[vitorgalvao]

My reasoning given in #4914 is that updating a cask is much more common than simply reading it. It’s also, from those two options, the time where understanding it is crucial — if you forget or overlook something, the cask breaks.

This is really the point I want to stress. Homebrew-cask (the project itself, and the commands) is what you use; reading it’s inner workings is atypical, compared to editing them. The working interface should be geared towards the users, but it’s organisation should be geared towards collaborators (and invisible to the user). Grouping stanzas should then be geared towards collaborators, to allow for an updating as quick, painless, and error-free as possible, while still making sense. Grouping a rarely changed stanza (if we reuse version, which is the idea) with the constantly changing ones, makes for a worse editing experience.

[tapeinosyne]

While I am personally indifferent to the proximity of stanzas during editing, your argument on the caskfile as a collaboration interface is sound.

In the absence of other/new opinions, I am in favor of merging this.

[rolandwalker]

I am also personally indifferent to the order when making updates. But @vitorgalvao is far more active on making the updates (and shepherding the updates of contributors), so I favor following his insights.

[tapeinosyne]

@vitorgalvao, @rolandwalker: we should establish a conventional position for the appcast stanza.

I suppose it belongs to the url and homepage group. Which order do we favor? I would suggest:

url '…'
appcast '…'
homepage '…'

When we reach an agreement, I will send a PR for a mass reformat.

[rolandwalker]

That sounds right.

[vitorgalvao]

Sounds good to me, as well.