Since we already have ABI, API resilience and Source Compatibility sections in the proposal template I think it might make sense to expand on that and make sure that proposal is considering not only correct
syntax/use, but also accounts for (even if basic) scenarios when new feature/syntax is used incorrectly
or in an (temporary) unsupported way.
I think it would make sense for proposals to state explicitly, in a separate section, what is supported and what is not (listing possibilities for future improvements), what is the possible initial set of diagnostic messages and some basic error/warning scenarios as well as what are the ways current feature might interact with other features already implemented in the language.
New attributes/keywords could be a good example - it would be very helpful to list contexts where new attribute/keyword could be used and what error message should be used for the rest. What are the
special cases and areas of the future improvement e.g. currently could only be used on functions
but later support could be expanded to properties and subscripts. How does new attribute/keyword
interact with existing ones e.g. @autoclosure vs. @escaping or @autoclosure vs. inout.
I think having documentation like that in the proposal would make implementation as well as code review much easier, and would be generally helpful for posterity.
Having worked on diagnostics for little bit now, I definitely +1 this!
While implementing diagnostics for the recent property wrappers proposals, it has often felt like trying to guess the intentions behind others' work without having their opinions represented. The diagnostic stories for new language features aid in discoverability and understanding of those features. Having those ideas laid out from the start could benefit both those of us creating diagnostics by giving us explicit understanding of what cases should cause failure, and the community as a whole by helping them understand how new features should and shouldn't behave. Thanks for bringing this up @xedin
+1 to this as well for all the above reasons! As the language continues to grow, I think it's important to consider how easy it is to learn about new features by trying them out and experimenting, and good diagnostics are a big part of that.
I think this applies here too, where this might make sense for syntax changes but isn't generally necessary for additions to the standard library and similar.