[Issue 21718] New: Preview switches have insufficient descriptions

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=21718

          Issue ID: 21718
           Summary: Preview switches have insufficient descriptions
           Product: D
           Version: D2
          Hardware: x86_64
                OS: Linux
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: dmd
          Assignee: nobody at puremagic.com
          Reporter: tobias at pankrath.net

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.

--