Transitioning Casks to DSL 1.0 starting 8 Sep

[rolandwalker]

This is covered in #4688, but I'm opening a separate issue so that the transition gets more notice.

DSL 1.0 starts 8 Sep

Starting 8 Sep, we can start using the new DSL forms, and transitioning all Casks. It's a large change, and there will probably be a few unforeseen bumps in the road.

Docs go first

I will start with documentation. Not everything in #4688 actually has functionality behind it. Some things are just stubs. We should put all of it in CASK_LANGUAGE_REFERENCE.md, including the stubs, and mark the old forms as deprecated.

Transition period

The old DSL forms work fine, so we can ease the pain with a transition period during which deprecated forms are still used.

But hopefully in this case the transition phase will not be too long. The goal is to get to #3066, after which point only DSL 1.0 will be supported.

#5365 (first line) goes last

Changing Casks to use the new form in #5365 should go last. Most of the other changes will helpfully prompt users to upgrade via a method_missing catchall. After changing Casks to use #5365, users will get cryptic errors.

Increased workload

We should be ready for additional workload as duplicate issues will be filed for some time. The answer is to

$ brew update && brew upgrade brew-cask && brew cleanup && brew cask cleanup

We might put a banner on README.md as we did during the Tap migration.

Cask authors will also need extra assistance for some weeks. 800 contributors will not all stop all at once to read the lengthy updated CASK_LANGUAGE_REFERENCE.md. Some contributors will probably be annoyed. We should refer them to #4688 and #4678, and explain that this is part of building brew cask upgrade.

[rolandwalker]

Forgot to ping @caskroom/maintainers .

[mAAdhaTTah]

I'm sorry if this is off-topic, but I've been watching this development for a while and I have no idea what DSL stands for... Would you mind filling me in?

[vitorgalvao]

@mAAdhaTTah Domain-specific language.

[rolandwalker]

@leoj3n while I'm sure it is meant as a joke, I'm going to delete the comment. You can contact me in IRC if that's a problem.

@mAAdhaTTah it's not off-topic, and no problem if it was. The purpose of this issue is just to discuss and raise awareness on what is changing.

[mAAdhaTTah]

Makes sense, thanks!

[rolandwalker]

@caskroom/maintainers and all other interested folks: transition starts today.

We can use some mnemonic versioning to set landmarks around the change:

• As of this morning, we are at version 0.39.3.
• I will cut a release now, bumping to 0.40.0. 0.40 means "should support all of DSL 1.0". But the transition is still happening.
• When the transition is done, no matter where the version is, we will bump to version 0.50.0, which means "only supports DSL 1.0"
• So DSL backward compatibility ends on version 0.50.0.

The rationale is to help when processing bug reports.

[rolandwalker]

I did add a banner to README.md in #6072, but tried to keep it reasonably short.

If you are a Cask author, please refer to cask_language_deltas.md, and feel free to PR work-in-progress Casks during transition. The maintainers will be happy to help.

There will also be mass-updates to Casks, and merge conflicts.

[TheZoc]

I need to ask something: How this works for already-installed casks ?
Should we wipe our installed cask collection and start fresh after brew-cask is upgraded to 0.50.0 ?

@rolandwalker The link https://github.com/caskroom/homebrew-cask/issues/doc/cask_language_delta_1.0.md gives me a 404 error.

Thank you guys for your hard word and it's great to see how everything is evolving! :D

[rolandwalker]

Thanks for catching the 404 — should be fixed now.

All your installed software is unaffected. There is no need to re-install.

However, only newly-installed software will gain the new uninstall features. But those features are not even here yet; this is only the preparation.

When we do add those uninstall features, we will also add some documentation/warning messages to help out users. But even then, already-installed software will continue to function.

[j6s]

How are existing casks handled? Are you changing them all at once or should one create PRs with updated versions?

[rolandwalker]

We are changing the existing Casks stanza-by-stanza. First, we document the new forms (as in #6121, #6137), then we alter the Casks (as in #6123). Note that I messed up #6123 — it has uninformative commit messages. #6174 is better.

Anyone is welcome to help with the changeover as mapped out in #4688, though it might be good to coordinate in IRC. For example, I have already prepared the transition from link to app, but not pushed.

As for PRs on individual Casks, don't worry too much. It's better to use whatever is the latest state-of-affairs as documented in CASK_LANGUAGE_REFERENCE.md and cask_language_deltas.md. However, if a Cask gets in using the old forms, that is no big deal. We will catch it later.