I'll certainly not try to go against a “how do we teach this?" in the proposal. Yet, in this very particular case, we enhance try?
in order to make it do the expected thing. What goes without saying is the easiest thing to teach: you simply don't have to say anything.
Yet, in our particular case, we still have to care about teaching the breaking change. There should lie the teaching efforts.
BTW, teaching is not about describing the consequences of the proposal. That is already handled in the "motivation", "proposed solution", and "detailed design" chapters of the proposal. There's no point repeating them. Teaching is something different: it is about putting people in the state of mind that makes them able to put the proposal at work for their very own purposes. Have them "grok" the change. Make them think "this is exactly what I need", or "this change will finally make this Swift feature usable". It's very personal. It's about convincing users that a new tool has its place in their own toolbox.
I'd thus write the teaching section for this proposal as a purpose-oriented guide, which would talk about:
- differences between Swift 4 and Swift 5.
- an explicit note about how simpler Swift 5 code generally is.
- how to "get back" the Swift 4 behavior in Swift 5 (with an explicit do { try ... } catch { ... })
- how to change code when compiler version bumps from 4 to 5 (change may be handled by a migration tool (how?), but it may also have to be done "by hand" (how?)).
- how to write code that is compatible with both Swift 4 and Swift 5 (with
as? T
).