# Design meeting 2022-11-16

## Links

https://github.com/rust-lang/lang-team/issues/179

https://blog.m-ou.se/rust-standard/

## Things to discuss

(copied from https://github.com/rust-lang/lang-team/issues/179 )

Standardization comes down to, basically:

1. Having an accurate specification (a document)
2. An (open?) process for evolution of the language
3. Stability

Rust currently already has 2 and 3, but not 1.

It'd be wonderful if we had an official Rust specification, which is kept up to date and distributed together with each new release. (I suppose this would effectively mean completing/upgrading the Rust Reference.)

Questions to discuss:

- Do we want this at all?
- What are the goals we aim to meet? (Audience and purpose.)
- How do we want to do this?
- Writing a specification involves a lot of tedious work, so it's unlikely to happen entirely from volunteer contributions, unlike many other parts of the Rust project.
- We could ask the foundation to fund the work. E.g. by hiring a technical writer/editor who will collect the information and write it down in a draft that the team(s) can approve or give feedback on.
- What form/structure should the spec have?
- We could take the Ferrocene spec as a starting point, or we could take the current Rust reference as starting point, or we could come up with something else.
- What should the scope of the spec be?
- Should it include the standard library? (Just core, or also alloc and std?)
- Should it cover all editions and all versions? Or only the latest ones? (Or only the latest version+edition accurately, but with notes everywhere that say in which edition or version a feature was introduced as useful (but not necessarily accurate/complete) context.)
- Should it cover things like `rustc` flags and details about `cargo` (and `build.rs`)?
- How about proc macros? (And the `proc_macro` crate?)
- Should it include our (still nonexistent (?)) memory model?
- Should it also document our stability guarantees?
- Should it specify exactly which programs are accepted and rejected? Or should it focus on specifying the behavior of accepted programs? (And leave it to "cargo check" which programs are accepted. That'd allow us to skip specifying the exact details of the borrow checker for example, while still specifying the behaviour of any compiled Rust program.)
- How should it tie in to our existing language evolution processes?
- Do we expect RFCs to include a diff/patch for the spec? (I think no.)
- Should it be required for the spec to be updated to include a new feature when it is stabilized? (I think yes.)

## Comments

### I have a question, what should I do?

nikomatsakis: Just make a new section and write it :)

### Are there public drafts of the Ferrocene spec available?

nikomatsakis: I'm wondering about public drafts of Ferrocene spec. I'm also curious to hear more about efforts to link the spec with the codebase.

pietro: yes, https://github.com/ferrocene/specification - https://spec.ferrocene.dev
pietro: all the content we have is public in that repository (drafts for new chapters are done in google docs, but put it into the repository as soon as they're ready)

### Other "prior art"?

pnkfelix: What other languages besides C and C++ might we look at as we think about patterns to duplicate, and anti-patterns to avoid?

* Java has the Java Language Specification, and (IIRC) a separate specification for the JVM itself.
* ECMAscript has its specification
* Scheme has the series of R1RS-R7RS documents, one of which (R4RS?) was turned into ANSI Scheme.
* Ada has the Ada Reference Manual (the "ARM")
* ARM (the CPU this time) has an extensive partially machine-readable ISA reference (and there are tools to translate it to other langauges, including theorem provers)
* Python is very ad-hoc, having multiple implementations but one "reference" implementation, and the surface area of what people care about turned out to include the CPython API

Josh: Re "anti-patterns", see ISO/ANSI/etc

Ralf: Also see the huge ambiguities in C/C++ (independent of the standards body that releases the document)

### Do we have consensus on the questions Mara posed above? Which ones are furthest from consensus?

Can we talk through the questions above, and see where we are on all of them?

### What's the most useful way we can present an "incremental" specification?

For instance, if the answers to some of the questions above are things like "yes, we should standardize core/alloc/std, but in that order of priority", then how do we most usefully evolve the standard?

### Ada Lessons Learned

We tried postponing working on wording for the specification, and just created more informal descriptions of new features, but it was a dismal failure.

The updates to the wording probably need to be part of the final approval process of each new feature proposal.

This requires strong agreement on a standard vocabulary, and a standard structure for each section.

("wording" as opposed to?)

Did Ada have a concept of "unstable feature" or "feature proposal" versus "implemented feature ready to standardize"?

joshtriplett: Failure that you suggest we avoid is a huge batch of changes and attempting to add standards language for all at once? Would that apply to, for instance, if we added a single feature, waited for it to be stabilization, and made a condition of stabilization be adding it to the spec?

tuckertaft: I'd do it earlier and define a delta. It's helpful to see what the delta looks like in context.

joshtriplett: So, ask for the feature to propose a delta to the spec, even if we don't merge that delta until we stabilize?

ralf: have the PR ready to be merged.

tuckertaft: we have a format for English language diffs. When you get into trouble is two enhancements updating the same paragraph.

ralf: I hope the spec will not be all just English. :D
:+1:

tuckertaft: standard structure for each section, standard vocabulary, has been very useful. "what is the syntax, what is the legality rule (compile time checks), what are the static semantics, post-compilation checks (link-time checks), and runtime checks".

Add non-normative stuff (rationale, tips for implementors) at the same time, since that's info you build up. We distribute an annotated reference manual that includes those. I often find the philosophy ("what are we trying to accomplish") very useful.

### How to relate to the Rust reference -- also, we've had trouble staffing that effort

nikomatsakis: we've had trouble maintaining and finishing the rust reference manual. I guess this is just echoing Mara's point about volunteer labor.

Josh: Eric Huss has been doing a lot of that work, and is interested in having a reference-review/reference-addition hack session with lang folks to get a bunch of things unblocked.

### Is there one specification or are there many specs for different aspects (type system, op.sem, library, ...)?

joshtriplett: semantically, what's the difference between multiple specs and a multi-part/multi-chapter spec?

ralf: I guess it speaks to the organization of the spec (from what Tucker said, the Ada RM seems to be organized by feature, not 'phase'), gonvernance aspects, ...

### What is the goal of the spec? Is it to allow independent implementations, or something else (e.g. verification tools, source of truth for rustc, ...)?

### Do we want this at all?

probably yes, but it'll depend a lot on the goals

### What are the goals we aim to meet? (Audience and purpose.)

One question is do we want to have multiple implementations.

joshtriplett: Not primary goal, which should be documenting behavior in a way that people can rely on, but this would be helpful for alternative implementations that arise.

skade: the ferrocene spec has mentioned particularly that it's not intended for alternative compilers. It's meant to start by documenting *what we know about rustc*, which is a hard enough problem. Constraining that problem first, take steps towards what we want, rather than solving all problems at once. We have an editing team towards that goal and can definitely help.

Some text from above:

Helping Rust run in high-assurance contexts (e.g. vehicles / medical devices) and meet the requirements of those contexts.

Enabling work on Rust formal methods.

Not primarily to enable multiple implementations.

tmandry: I wouldn't say no, but if we've had trouble maintaining reference, is this the right thing to direct our resources to currently? Why now, what value does it bring?

pietro: Three goals we could decide to consider

- what does rustc do
- regulated environments (surprisingly similar to the first one), maybe worth digging into the requirements
- multiple implementations

are there other goals?

mara: marketing, perception of maturity

joshtriplett: yes, but people say they don't take rust seriously for many reasons

pnkfelix: is "What does rustc do" meant to talk about the future? I think one reason is to be clear about what behavior change in the future, especially around unsafe code.

nikomatsakis: Goal with things like a-mir-formality has been better communication between Rust teams, helping us do a better job and scale up.

Tucker: Common level of specification across the language, rather than well-understood parts and hazy parts. Know how things relate.

joshtriplett: More thorough definition makes it *easier* to recognize when the intended behavior and actual implementation are differing.

joshtriplett: to some extent it will happen one way or another, either it happens with us, or without us, I think we really want it to happen with us. It makes a lot of sense to do direction setting. We see right path being this kind of doc and participation model (e.g., RFCs, open-source).

skade: My experience is the people who care about spec as a tool don't care about where it comes from. Main reason people want to use it is that they follow engineering principles where they base their tools on things they can rely on. The spec says what compiler should do. If it's not in the spec, you shouldn't expect it to do that. Questions like "how exactly does type inference behave" is not necessarily the level that our spec needs to be operate on -- useful, but not an industry problem. Only have to say "type inference happens, you can rely on X, Y, and Z".

joshtriplett: Reference tool for people getting especially clever and pushing the language very hard, and wanting to have clear boundaries. *Not* using UB as a weapon (let's make that a non-goal), but nonetheless trying to have detailed documentation about what people can and cannot rely on.

mara: last item is related. spec could either specify which programs are accepted/rejected, but we could decide to not specify the behavior of accepted programs. For critical safety stuff you want to know what your program, which does compile, will do what it is supposed to do. Limited use for second impl.

Ralf: works for some aspects of the language, but not for unsafe code. Just because the compiler doesn't throw an error at you doesn't mean anything. Even giving some rules that programmers have to follow... I think that's kind of what C/C++ does for UB, and we can find it a failure.

Mara: I'm saying we don't have to specify exact details of the borrow checker.

Ralf: Understood, but not all aspects are the same.

skade: There is some degree of freedom for our purposes, but I'm not opposed to specifying more than that, it's very cool.

tucker: Our experience with very high levels of integrity - it's important to specify what is and isn't legal. Very worried about code whose behavior is not fully defined. Need a strong gate. We've recently been specifying a compiler for simulink and it's important that we reject things that are outside the supported subset.

mara: doesn't have to be as strict, if there are some cases where compiler would give errors even though std doesn't specify that they should be rejected, not actually a problem, right, only the other way around?

josh: multiple impls will clearly look at the spec, and if it happens to fully fail to accept everything it should accept, that's not so bad, but worse if it accepts things that rustc (or spec) says you should reject. That effectively constitutes a language extension that people can come to rely on and then complain if another impl doesn't have it. I'm in favor of the incremental approach, but I do want to provide clear enough language that we make it clear going past this does not mean you are "compliant-plus", it means you're out of compliance.

tucker: agreed that failing more than it should is considered safer, so long as the failure is at compilation time. failing by generating bad code.

ralf: effectively UB.

mara: but rust is well setup to do that.

josh: e.g., in short term, if we specify requirements that "borrow checker will never accept a program that has this property".

skade: shouldn't confuse spec with standardization. Specifying the borrow checker and current behavior is very useful. We discuss this a lot, how do we deal with something like polonius, if we had a rust standard for how borrow checker behaves, innovations become problematic, it has more relaxed rules than the older version. This is something to find a strategy around.

One option might be saying the spec says references need to be borrow checked. Here's an appendix how NLL does it.

josh: looking at remaining questions. Some of them will be easier to go through quickly than others. "How do we want to do this" will take up all our time but we can prob get through "scope" or "evolution processes".

- How do we want to do this?
- Writing a specification involves a lot of tedious work, so it's unlikely to happen entirely from volunteer contributions, unlike many other parts of the Rust project.
- We could ask the foundation to fund the work. E.g. by hiring a technical writer/editor who will collect the information and write it down in a draft that the team(s) can approve or give feedback on.

Mara: How do we want to do this also has to do with role of foundation--

josh: --or folks that aren't in this meeting.

mara: I discussed this some and said this kind of work is unlikely to happen accurately and fully with just volunteers. Won't get to a full spec by relying on volunteer contributions. Hiring an editor or something would help. Decision of whether this document is "officially Rust" would still be up to Rust teams. Seemed positive about this idea.

ralf: I can speak for some small corners but I feel like doing this kind of technical writing requires you are in the process. I'm not sure you can write this down unless you actually understand what it's all about. Finding something who can do the tech writing across the board seems unlikely.

mara: wouldn't expect this person to write every single word, they would be the ones incorporating edits, making sure it's complete, finding what's missing, pokes people to write that, overall coordinator. Someone used to technical writing.

pietro: a big chunk of the specification was written by person that learned rust the hardest way in the world. Learned Rust by specifying Rust. But he had a lot of knowledge about lang/spec and some people that knew the language and could provide context, doesn't have to be someone who is compiler engineer, but people in this room have to be there to give pointers. (Also, as we've said publicly, we'd love to upstream what we wrote, but the legal constraint is that we can only donate it to a legal entity, e.g., foundation. How that would work on the editing process, and how to keep control, would be something for project to decide. But we can't transfer repository to rust-lang org directly.)

josh: though license is permissive, as well.

josh: Scope question: which teams are involved? Proposal: after we've established top-level requirements, the various teams should "own" review/approval of their relevant portions of the spec. e.g. lang, libs-api, compiler (for standardized "surface area" of things like compiler options) cargo

nikomatsakis: I think the a-mir-formality (and maybe minirust) could be included by reference, potentially. That might serve that purpose Florian mentioned.

Tucker: A little dubious about hiring someone to do this. The first few chapters need to be written by a Rust expert. We made do but would've been better to have a rust expert involved. We did our best but you have to make some decisions. Choose the right vocabulary, choose the right structure. If you have five examples, five sections -- not something a hired writer can do. Requires this kind of team to discuss/review. We've tried to do that with Ferrocene, but we need more exposure, meaning more experts, to weigh in. e.g., what is a name, entity, resolution? Rust literature doesn't fully agree on vocabulary.

joshtriplett: i.e., when you said first few chapters, you didn't mean the first few in order, but rather the first to get written, as they set an example.

Tucker: Right.

skade: copyright needs to be donated to foundation is (a) it becomes a very clear process, it's sort of unclear what happens without a legal entity; and (b) it works better for the companies who want it as an industry tool to have an entity. We do have editing staff and we can offer that as a stopgap, but I agree that because there are multiple interests, and we're targeting our own, in the end it's a doc tool for all of us, so I'd like to say that just because it has the current format, doesn't mean there couldn't be another one.

mara: about person, doesn't have to be writer, would ideally be familiar with technical editing, but the main purpose would be coordinating. Finding the answers to the list of questions below -- not answer them, but asking people and coordinating this thing to some kind of consensus. And the same for the work that comes afterwards. Coordinating opsem group with the teams we have. I don't think a volunteer will do this. Doesn't have to be a person new to Rust, could be someone in this room.

ralf: I think it's not just no-one feels responsible, it's also that many of the questions can't be answered in isolation, we lack the framework to put the answers in. Don't want to answer them in isolation. There is a bunch of groundwork, certainly on the opsem side, structure that needs to be laid down, to agree on vocabulary, framework, so that we can go to the lang team and ask them to sign off.

tmandry: maybe foundation needs to sponsor multiple people in different parts of the project to get this process started. Not everyone who works on it has to be sponsored by foundation but that would prob be helpful to making it happen.

josh: next steps?

nikomatsakis: I feel like an RFC about process would be useful.

joshtriplett: scope will affect what teams are there to decide.

mara: I think we can make decision without settling all the details of the scope.

joshtriplett: I think it'd be useful to say "the scope may expand to include X in which case sign-off would be owned by team that owns X".

*discussion about a process RFC that specifies more the how, clarifies that the final decisions remain with teams*

ralf: in UCG, some place where we could use help is less in writing the spec, and more in summarizing the existing discussion on issues. Many of them need a write-up: here are the 2 or 3 positions that seem reasonable, and the arguments. Keeping track of the insights we've had during the discussion and summarizing them so that the nice person doesn't have to read a 180 comment thread...not writing the specification, but faciliating the process.