Manage content on the C# 7 draft specification work

[BillWagner]

The C# standard committee will soon begin reviewing and merging feature PRs for C# 7.x features. There are a number of docs tasks that need to happen. some require discussion:

• Update TOC labels to reflect version: "C# 6.0" should be replaced with "C# 7.x" in the following locations:
  • Table of contents
  • Breadcrumb
• Remove feature speclets from docs.microsoft.com

When to remove speclets requires some discussion:

The speclets won't be removed from the dotnet/csharplang. They remain useful for historical purposes, and to better understand why different decisions were made.

Where to redirect links?

When the speclet is retired, all internal and external links to the version published on docs will break. Internal links are easy: We'll catch those in the build, and re-target to the best location in the updated standard. We handle external links by configuring redirections. Where should we send those links?

For some of the features, multiple clauses in the standard will change. See the draft PRs for examples. Some of the PRs will be obvious (new literal additions is an example). Others change several areas (pattern matching is an example). Current options would be:

• The first location in the standard where the feature is introduced. This would more often be the lexical analysis chapter, where the grammars are defined. Some may not introduce new grammar, and would be in a different chapter.
  • Advantage: The first introduction will likely have forward references to other locations. That may be less likely in later mentions.
  • Disadvantage: The grammar will not have as much information as many of the other clauses.
• The "largest change" for a feature. This would link to the location where the behavior is described in most detail.
  • Advantage: It will likely go to the clause that has the most detailed description of the behavior for the feature.
  • Disadvantage: It likely won't link to everything related to the feature, and it may be anywhere in the spec.

I'm leaning toward the "largest" change for a feature (even though that's subjective). I'd like responses in the comments.

When to retire speclets?

The second question is when to make the PRs to remove speclets now incorporated in the standard. There are two reasonable options:

• All at once, when the C# 7.x draft standard is submitted to ECMA.
• As each feature PR is merged.

I'm leaning toward as soon as the feature PR is merged. That avoids any discrepancies in the descriptions that the standards committee has resolved. One concern could be if there are links between speclets of features that have been merged, and those that haven't. I think that will be handled by the committee for ease of managing the features for each release. Again, I'd like comments.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 85c9d0ef-c6b0-87f2-746d-6940b1377a54
• Version Independent ID: 575e8c7c-a170-a9d0-ee59-c42451cd1ac9
• Content: Table of contents - C# language specification
• Content Source: standard/README.md
• Product: dotnet-csharp
• Technology: csharp-spec
• GitHub Login: @dotnet-bot
• Microsoft Alias: wiwagn

[CalvinAllen]

Are there any examples of what was done in the past?

Either way, I’m inclined to agree with your suggestions since there seems to be a lot of thought that went into it.

[BillWagner]

Are there any examples of what was done in the past?

Not yet. This is the first time we're updating the standard in public when the feature specs were also in public. (It's fun to write that last sentence).

[KathleenDollard]

Redirects: I have a slight lean to the first occurrence. I think anyone who is reaching back to speclets may want the full feature, and at least will be more patient to multiple hops. Your description of that as the most complete set of links drives my opinion here.

When: Whatever is reasonably easy for the folks working on this. I do not see this as a big issue. I agree that there should be a decision for consistency.

[CalvinAllen]

Is there any chance of getting an example that would be changed?

I.e., a link to a speclet and then where it would redirect to in either case?

I feel like "seeing" what's going to happen might help?

[BillWagner]

Is there any chance of getting an example that would be changed?

Good point. When dotnet/csharpstandard#104 is merged, this speclet can be removed from docs.

This is a good example for the following reasons:

1. The PR updates 4 different clauses.
2. Most of the feature is described in the one new section in Statements.

Another good example is dotnet/csharpstandard#236, which would replace this article.

The most extreme example is dotnet/csharpstandard#63. It's more extreme because the feature spec for Tuples was never in the dotnet/csharplang repo, but the updates for inferred tuple element names and tuple equality are published.

Note that the committee will get to many of the smaller features before tackling Tuples, which is the spec is changing the most.

[CalvinAllen]

In the case of your first example, where would - https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-7.0/local-functions - redirect to after its removal?

Sorry for all the questions, just not 100% clear on where it would go 🙂

[MadsTorgersen]

Where: I think we should strive to redirect to the place that most fully describes the new feature. I think it's likely to be the most useful. Folks that want to dig into the full set of changes associated with the feature can do so via the PR that introduces it.

When: Agree that this should be consistent, and vaguely lean towards doing them as they become ready.