The #[diagnostic] attribute namespace

text/3366-diagnostic-attribute-namespace.md

@@ -71,32 +71,50 @@ I expect the new attributes to be documented on the existing [Diagnostics](https
 
 This RFC proposes to introduce a new `#[diagnostic]` attribute namespace. This namespace is supposed to contain different attributes, which allow users to hint the compiler to emit specific error messages in certain cases like type mismatches, unsatisfied trait bounds or similar situations. By collecting such attributes in a common namespace it is easier for users to find useful attributes and it is easier for the language team to establish a set of common rules for these attributes.
 
+Attributes in this namespace are generally expected to be formed like:
+```rust
+#[diagnostic::attribute(option)]
+```
+where several `option` entries can appear in the same attribute. `option` is expected to be a valid attribute argument in this position. Attributes in this namespace are versioned. Any incompatible change to an existing stable attribute in this namespace requires bumping the version of the diagnostic attribute namespace. Crates using these attributes must specify the expected version of the diagnostic namespace via a `#![diagnostic::v{version_number}]` crate top-level attribute. If multiple such attributes are present the compiler will choose the highest version number and ignore the rest. The compiler is encouraged to provide a lint for outdated versions of the diagnostic attribute namespace. This mechanism exists so that a third party crate can provide a shim implementation of the corresponding attributes to translate between different versions of the diagnostic attribute namespace on different rust versions.
+
 Any attribute in this namespace may:
 
 * Hint the compiler to emit a specific error message in a specific situation
+* Only affect the messages emitted by a compiler in case of a failed compilation
 
 Any attribute in this namespace is not allowed to:
 
 * Change the result of the compilation, which means applying such an attribute should never cause an error as long as they are syntactically valid
+* pass-through information from the source of the diagnostic in a way that users can rely on. E.g. Such an attribute should not allow users to keep the compilation successful and dump information about `extern` blocks to generate C header files
 
 The compiler is allowed to:
 
-* Ignore the provided hints
-* Use only parts of the provided hints, for example for the proposed `#[diagnostic::on_unimplemented]` only use the `message` option
-* Change this behaviour at any time
+* Ignore the hints provided by:
+    + A specific attribute
+    + A specific option 
+* Change the set of supported attributes and options at any time
+* Provide warning lints for malformed or otherwise not accepted attributes 
 
-The compiler must:
+The compiler must not:
 
-* Verify that the attribute is syntactically correct, which means:
-    + Its one of the accepted attributes
-    + It only contains the allowed options
-    + Any provided option follows the defined syntax
-* Follow the described semantics if the attribute is not ignored.
+* Change the semantic of an attribute or option, these kind of change requires a bump of the diagnostic attribute space version number
+* Emit an hard error on malformed attribute, although emitting lints is fine
 
+Adding a new attribute or option to the `#[diagnostic]` namespace is a decision of the compiler team. The envisioned procedure for this is as following:
+
+1. The new attribute lands on nightly without a feature gate. It gets ignored on stable/beta until its explicitly activated there.
+2. The time as nightly only attribute is used to verify that:
+    * The attribute solves a real problem
+    * The implemented syntax matches the expectations
+3. To enable a certain attribute in stable release the following steps are required:
+    * The attribute is documented in the rust reference
+    * T-lang is informed
+    * T-compiler performs a FCP, where a simple majority (>50%) accepts the attribute
+
 
 ## The `#[diagnostic::on_unimplemented]` attribute
 
-This section describes the syntax of the `on_unimplemented` attribute and additionally how it is supposed to work. Implementing the later part is optional as outlined in the previous section. Any syntax not explicitly described in this section must be rejected as invalid according to the general rules of the `#[diagnostic]` attribute namespace.
+This section describes the syntax of the `on_unimplemented` attribute and additionally how it is supposed to work. The specification of this attribute is partially provided as example and motivation for the `#[diagnostic]` attribute namespace. In addition it is provided to give this RFC a 
 
 ```rust
 #[diagnostic::on_unimplemented(
@@ -116,7 +134,7 @@ In addition the `on_unimplemented` attribute provides mechanisms to specify for
 
 The `any` and `all` options allow to combine multiple filter options. The `any` option matches if one of the supplied filter options evaluates to `true`, the `all` option requires that all supplied filter options evaluate to true. `not` allows to negate a given filter option. It evaluates to `true` if the inner filter option evaluates to `false`. These options can be nested to construct complex filters.
 
-The `on_unimplemented` attribute can be applied multiple times to the same trait definition. Multiple attributes are evaluated in order. The first matching instance for each of the `message`/`label`/`note` options is emitted.
+The `on_unimplemented` attribute can be applied multiple times to the same trait definition. Multiple attributes are evaluated in order. The first matching instance for each of the `message`/`label`/`note` options is emitted. The compiler may lint against ignored variants as this is the case for `match` arms for example.
 ```rust
 #[diagnostic::on_unimplemented(
     if(Self = std::string::String),
@@ -164,6 +182,10 @@ Another drawback is that crates might hint lower quality error messages than the
 
 This proposal tries to improve error messages generated by rustc. It would give crate authors a tool to influence what error message is emitted in a certain situation, as they might sometimes want to provide specific details on certain error conditions. Not implementing this proposal would result in the current status quo. Currently the compiler always shows a "general" error message, even if it would be helpful to show additional details.
 
+There are alternatives for the naming of the `#[diagnostic]` namespace:
+
+* Use a `#[rustc]` namespace for these attributes. This would signifies that these are rustc specific extensions. We likely want to encourage other rust implementations to utilise these information as well, therefore a more general attribute namespace seems to be a better solution.
+
 There are alternative designs for the proposed `on_unimplemented` attribute:
 
 * The `on()` based filtering might be replaceable by placing the attribute on negative trait impls. This would turn a filter like
@@ -196,17 +218,6 @@ Notably all of the listed similar features are unofficial language extensions.
 
 Clarify the procedure of various potential changes prior stabilisation of the attribute namespace:
 
-* Process of adding a new attribute to the `#[diagnostics]` attribute macro namespace
-    + Requires a RFC? (t-lang seems to prefer that?)
-    + Requires a language/compiler MCP? 
-    + Just a PR to the compiler?
-* Process of extending an existing attribute by adding more options
-    + Requires a RFC?
-    + Requires a language/compiler MCP? 
-    + Just a PR to the compiler?
-* Process of removing support for specific options or an entire attribute from rustc
-    + Requires a compiler MCP? 
-    + Just a PR to the compiler?
 * Exact syntax of the `on_unimplemented` attribute
     + Can `Self` be accepted in that position or do we need another name?
     + Is `if()` a valid identifier in the proposed position?