Bug 21718 – Preview switches have insufficient descriptions

For example -preview=nosharedaccess 1. Does not state what is does 2. A corresponding description can not be found on dlang.org - google has three matches on dlang.org, all hitting the changelog - but there is no changelog entry introducing the switch, just fixes 3. A broader search finds the PR in which Walther introduces it with a link to a DIP draft 4. The draft was merged, but could not be traced to the actual DIP number All in all, that's very poor. What I propose is that we treat -preview switches like bazel treats --incompatibel: https://www.bazel.build/maintaining/breaking-changes-guide.html 1. The doc of the switch points to a github issue (or here) with a description of 1. What the change does 2. The description contains a migration recipe, to explain users how they should update their code. Ideally, when the change is mechanical, include a link to a migration tool. 3. The description includes the intended length of migration window. 4. The description includes an example of the error message users will get if they don’t migrate. This will make the GitHub issue more discoverable from search engines. Make sure that the error message is helpful and actionable. When possible, the error message should include the name of the incompatible flag. Linking the DIP is not enough, as it misses 2. 3. 4.

@ntrel created dlang/dmd pull request #16345 "Fix Bugzilla 21718 - Preview switches have insufficient descriptions" fixing this issue: - Fix Bugzilla 21718 - Preview switches have insufficient descriptions Add links. https://github.com/dlang/dmd/pull/16345

dlang/dmd pull request #16345 "Fix Bugzilla 21718 - Preview switches have insufficient descriptions" was merged into master: - fb492bfa8dceca2c1f0cc0fa5c91ed37a3e8e110 by Nick Treleaven: Fix Bugzilla 21718 - Preview switches have insufficient descriptions Add links. https://github.com/dlang/dmd/pull/16345