Compiler UX Guidelines RFC

[Havvy]

This RFC proposes conventions for the user experience of the rust-lang/rust compiler.

• Pre-RFC
• Reddit Discussion
• Rendered

[tshepang]

I would rather have the "when developer lives are better" sentence removed. The first part does not necessarily follow the second.

[Havvy]

@tshepang I did both changes. The latter does follow though. If developers are spending less time trying to learn their tools due to accidental complexity in the tools, that's less time they can spend working on their customer's actual needs. Of course, they could spend the time somewhere else (e.g. drinking a beer), but that's why the word was "can". But it's fluff nonetheless, so was for the best to be removed anyways.

[llogiq]

The 'note' should be formatted as code.

[llogiq]

Perhaps we want to ask implementers to think about orthogonality when adding flags, e.g. if we'd have a json-emitting variant of multiple actions, an additional --json flag could be better than adding --first-action-json, --second-action-json, ... for each action.

[llogiq]

Why is there no shepherd assigned to this RFC?

[nikomatsakis]

@llogiq because the compiler team has only recently started having having regular triage meetings. we're assigning one now. :)

[Havvy]

Hey @pnkfelix ;

@llogiq - I added the note about the orthogonality of flags.

[Havvy]

Is there any reason to not go into "final comment period"?

[steveklabnik]

A shepard was only even assigned a day ago, so I would think it's a bit early.

(ie, it's their job to asses this question 😄 )

[aturon]

cc @wycats

[nikomatsakis]

So I gave this a read. I agree that it seems to reflect current practice, which was the goal. I have some thoughts about things we might do to improve, but this is presumably not the place to argue them. Anyway, TL;DR, seems good to me -- that said, I do think it's worth considering just where these guidelines ought to live long term. An RFC doesn't quite seem right. A ux-guidelines.md file in the source repo is perhaps better. (What directory?)

[Havvy]

Fixed the missing closing quote;

I originally proposed adding a file directly to the rustc, but that issue was closed in favor of having an RFC to bikeshed and come to a consensus that they were good guidelines. The original goal has always been to have this file handy for developers in the rustc repository.

As for which directory - I'd say just shove it into /docs/ux-guidelines.md or possibly create a /docs/guidelines directory and shove it in as ux.md but also put in other similar RFCs guidelines such as the backwards compatibility RFC. Just tell me where to put it, and I'll put it there.

But I definitely want to be the person who puts it there -- I (selfishly) want my name on the commit so I can point to others exactly how I've contributed to the Rust project.

I'd also really like to hear your thoughts on what can be improved that's not currently being done. Possibly with a blog post; possibly with RFC(s) to add them as new guidelines?

[pnkfelix]

There is also a family of options that are collectively guarded by -Z unstable-options, but perhaps that is transitively covered by the above bullet.

[pnkfelix]

@Havvy hi

The compiler team discussed this recently. I think we all agree that the document you've written here codifies our current practice, and that we just need to resolve the bikeshed of where to put it.

Beyond that, here are some personal opinions:

I personally have no problem with putting the document into src/docs/.

The file itself should probably be named rustc-ux-guidelines.md: that is, I would put rustc into the name, since there are libraries elsewhere in the Rust distribution that are not part of the compiler and the several of the guidelines discussed here don't make sense outside the context of the compiler.

• That, or the file should have one section for the few guidelines given here that do apply to the project as a whole, and then a separate section for the bulk of the material specific to the rustc user experience.

---

Anyway, having said all that, I suspect that if no one else chimes in soon (within a day or two) then a great next step would be to just open up a pull request that creates the aforementioned file in src/docs/. (And in the PR description, just as you did for this pull request, link to this RFC.)

[Havvy]

@pnkfelix This can be merged or closed, yes?

[pnkfelix]

@Havvy yah thanks