Improve docs around new diagnostics #15330
Conversation
|
It feelks like it either belongs to or needs to be linked from the |
|
I guess linking to the diags page from the dev guide is reasonable! |
|
|
||
| 1. Create a pull request that reserves an error message. (That way, you can avoid other people trampling over your change to FSComp.txt while you're implementing the actual feature.) [Here's a historical example.](https://github.com/dotnet/fsharp/pull/14642) | ||
| 1. In the same pull request, reserve the new feature. [Here's a historical example](https://github.com/dotnet/fsharp/pull/15315/) (although it would have been better practice to combine this into the previous pull request, and also this pull request [should not have registered the feature](https://github.com/dotnet/fsharp/pull/15315/files#r1220330247) as belonging to a particular language version). | ||
| 1. Now you can go ahead and implement the diagnostic. This is the point at which you would register the language feature in some particular language version (likely the preview language version). It is often best practice to introduce it at a lower level than you ultimately intend (e.g. informational rather than warning, or warning rather than error), to permit a more gradual rollout. See the section on "[Enabling a warning or error by default](#enabling-a-warning-or-error-by-default)" for more information. |
There was a problem hiding this comment.
Hm from what I understand, the above PR examples are not entirely "canonical" (as in - things could be organized in a better way) hence the whole thing sounds a bit confusing. I'd suggest rather one of the following:
- Finding more canonical examples
- Removing them at all and adding once such examples appear
- Drawing some picture/diagram/whatever
There was a problem hiding this comment.
- Create a pull request that reserves an error message. (That way, you can avoid other people trampling over your change to FSComp.txt while you're implementing the actual feature.) Here's a historical example.
- In the same pull request, reserve the new feature. Here's a historical example (although it would have been better practice to combine this into the previous pull request, and also this pull request should not have registered the feature as belonging to a particular language version).
No, please don't suggest reserving error numbers or pre-registering features prior to implementing the feature. The checkin for the feature is the first place these should arrive in the codebase. Many features, spend months, some even spend years before being completed, or are closed incompleted. We definitely do not want orphaned partial changes checked in to the codebase.
Being able to manage merges and conflicts is a useful skill for developers to have.
|
At this point we don't want to encourage people to split features into multiple PRs. |
Pull request was closed
Rendered.
There are actually not all that many places which adhere to this, which is why I've linked to some imperfect PRs as examples.