Add $message_type field to distinguish json diagnostic outputs

[jsgf]

Proposal

Currently the json-formatted outputs have no way to unambiguously determine which kind of message is being output. A consumer can look for specific fields in the json object (eg "message"), but there's no guarantee that in future some other kind of output will never have a field of the same name.

This PR adds a "$message_type" field to all json outputs which can be used to unambiguously determine which kind of output it is. The mapping is:

diagnostic: regular compiler diagnostics
artifact: artifact notifications
future_incompat: Future incompatibility report
unused_extern: Unused crate warnings/errors

This matches the "internally tagged" representation for serde enums.

Implementation at rust-lang/rust#115691

Edit: Why call the field $message_type and alternatives?

• The $ prefix avoids any possible collision with a real field name in any of the message structures.
• message_type should help readers understand that this is specifically the type of the message, vs some kind of "type" contained in any of the messages themselves.

The rationale for choosing type specifically was that, as a Rust keyword, it has a very low likelihood of collision with a real field name that we actually want to use. I think kind is a particular risk for that, since its so widely used as a synonym for type because of the keyword collision issue.

Secondly, type is accurate since it's basically a reflection of the underlying rustc type being serialized into the diagnostic output.

Thirdly, it is a common (perhaps even the conventional) name used for this purpose - for example in the serde documentation.

message_kind (etc) would work of course, but be a bit verbose. There's a risk that this kind of name could be misunderstood as being part of the message content itself rather than as a designator/disambiguator (i.e. effectively external to the payload of the serialized structure) - more of a risk than type.

type could be confusing at first glance because it could be interpreted as referring to a type name pertaining to the diagnostic. However in practice this is unlikely because 1: a field isn't going to be called type because of the keyword issue, and 2: while the content could technically look like a type name, in practice it doesn't look much like a real one.

Mentors or Reviewers

@JakobDegen

Process

The main points of the Major Change Process are as follows:

• File an issue describing the proposal.
• A compiler team member or contributor who is knowledgeable in the area can second by writing @rustbot second.
  • Finding a "second" suffices for internal changes. If however, you are proposing a new public-facing feature, such as a -C flag, then full team check-off is required.
  • Compiler team members can initiate a check-off via @rfcbot fcp merge on either the MCP or the PR.
• Once an MCP is seconded, the Final Comment Period begins. If no objections are raised after 10 days, the MCP is considered approved.

You can read more about Major Change Proposals on forge.

Comments

This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.

[rustbot]

This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.

cc @rust-lang/compiler @rust-lang/compiler-contributors

[oli-obk]

since this is insta-stable

@rfcbot fcp merge

[rfcbot]

Team member @oli-obk has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Aaron1011
• @cjgillot
• @compiler-errors
• @davidtwco
• @eddyb
• @estebank
• @jackh726
• @lcnr
• @matthewjasper
• @michaelwoerister
• @nagisa
• @oli-obk
• @petrochenkov
• @pnkfelix
• @wesleywiser

Concerns:

• type field name is confusing resolved by Add $message_type field to distinguish json diagnostic outputs #673 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[oli-obk]

@rfcbot concern type field name is confusing

The first impression several compiler contributors (including me) had, was that the field will be storing a type that is somehow relevant to some diagnostics.

We should pick something that isn't confusable with other information that is often used in a similar context. output_kind, message_kind, or sth seem less ambiguous

[jsgf]

I updated the MCP with discussion on this point (ie a lightly edited version of the previous comment).

[jsgf]

What's the next step? Is there anything I need to do?

[oli-obk]

We need to wait for people to check their boxes. I'll review the zulip thread discussion again to see if the concern is resolved and we're happy to go with type as the field name

[oli-obk]

Please keep the non-organizational comments on the zulip thread

[RalfJung]

Sadly the link to the Zulip thread in the 2nd comment does not work any more. :/ And this thread also contains just a dead link. Where do I find the Zulip thread?

[jsgf]

This should work: https://rust-lang.zulipchat.com/#narrow/stream/233931-t-compiler.2Fmajor-changes/topic/Add.20.60type.60.20field.20to.20distinguish.20json.20dia.E2.80.A6.20compiler-team.23673

(I added the word "distinguish" to the title to help clarify it a bit)

[jsgf]

Renamed field from type -> $message_type. New Zulip discussion URL is https://rust-lang.zulipchat.com/#narrow/stream/233931-t-compiler.2Fmajor-changes/topic/Add.20.60.24message_type.60.20field.20to.20distinguish.E2.80.A6.20compiler-team.23673

(I think? It said it renamed it but the new one is empty?)

[oli-obk]

@rfcbot resolve type field name is confusing

[apiraino]

@rustbot label -final-comment-period +major-change-accepted

[rustbot]

This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.

cc @rust-lang/compiler @rust-lang/compiler-contributors

[apiraino]

MCP reopened because I closed it without waiting the FCP to reach completion. Sorry about that

[jsgf]

Are there any outstanding issues to resolve on this?

[apiraino]

No, you're right, the FCP has completed and probably this MCP can be closed as accepted without waiting any further.

@rustbot label +major-change-accepted