rust-lang / rust-lang/reference

Guidelines for implementation-specific rules

Open
#2,040 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Authoring guide Meta
Dominant language
Rust
Stars
1.6k
Forks
607
PR merge metrics
PR metrics pending

Description

I think the authoring guide should have guidelines for how to handle implementation-specific rules. Should they ever be allowed? Where does the line get drawn?

Some current examples:

  • Is the filesystem layout part of the language or part of the implementation?
  • All the various notes we currently have regarding rustc and cargo.

In the past, there has been a sentiment from some in the project to never allow that. I largely agree with that. However, I think there will be gray areas that will be difficult to navigate with such a prohibition.

Unspecified is slightly different which is noted in https://github.com/rust-lang/reference/issues/2026. This is more related to the C-style "implementation-defined behavior — unspecified behavior where each implementation documents how the choice is made".

Note that there is another category of this that is "target-specific" behavior, though I think we have resolved that in https://github.com/rust-lang/spec/pull/58 which is now in the authoring guide.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the authoring guide and the discussion in issue #2026 about unspecified behavior. Review the target-specific guidance from pull request #58 and compare it with the filesystem-layout, rustc, and cargo examples named here. Done means the authoring guide has an agreed boundary and guidance for implementation-specific rules, including gray areas.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.