T-spec meeting 2024-02-15

--- title: T-spec meeting 2024-02-15 tags: ["T-spec", "meeting", "minutes"] date: 2024-02-15 discussion: https://rust-lang.zulipchat.com/#narrow/stream/399173-t-spec/topic/Meeting.202024-02-15 url: https://hackmd.io/kQd4Yl9GRz-WALXvWMfS_A --- Attendees: Joel Marcey, Eric Huss, Monadic Cat, Lukas Wirth, TC, Connor Horman, Mara Bos, Pietro, Felix Klock, pnkfelix ## Potential Agenda - Specification Chapter Structure - Any Other Business ## Specification Chapter Structure https://rust-lang.zulipchat.com/#narrow/stream/399173-t-spec/topic/Structure.3A.20chapters/near/420245542 Eric: Good to have chapters on grammar, AST, etc. Mild concern, if you want to learn about some aspect of the language, you have to go to many parts of the specification. e.g., container operand is not mentioned in a chapter but only in the grammar chapter. It might create a jumpy flow that might be challenging to read. Mara: Feels like with a lot of specifications today that they are jumpy anyway. It requires different expertise to write about all the various aspects of, e.g., arrays, and breaking those aspects up into a higher level chapter could make sense. Connor: case of reading the spec to learn about Rust. Would want to read it to learn a subset of, e.g., Rust, instead of a subset of various levels of hte grammar. Best way to do it would be a high level approach. Type system and opsem of arrays instead of type system of arrays, structs, etc. Eric: How does the structure matter with the writing of the spec because you can stub things out? Mara: There is a lot of context switching that would take place by putting all semantics in one place. Can put responsibility on various teams when writing if they are broken out this way. Connor: Does this mean we need to be more clear about phase separation? Pietro: Why not both? Depending on the markup language we are using you can generate various versions and formats. Mara: What does it look like when we are writing it though? If we have a file called `arrays.md`, there can be conflict who is writing what aspect of arrays. pnkfelix: Wary of tooling that can present things on what people care about because as an author you care about how things are going to be consumed. Pietro: The source files can be one for grammar, type system, opsem, etc. For Ferrocene, for example, it doesn't matter if it is written one way or the other. If you have enough metadata to link various parts together, it doesn't block various formats. Mara: If looking at this document as a perfect matrix, then you could design it for different formats. e.g., there could be a huge difference between tuples and arrays. At another level, you may want to describe them as nearly the same thing. You may want a different section on for, while, infinite loops where as somewhere else you may want to talks about loops in general. Joel: Practicalities. The theory of how we layout the specification is important and interesting, but we also need to remember the practicalities of getting as spec written in a timely fashion. And we should highly consider which format can get us the most volunteers to help write the spec so that we can have content written more efficiently. Mara: If we went with the classical approach, no idea where to start. Even the example array drafts had gaps that were filled in different ways by other examples. If we have one chapter on grammar and AST, it is easier to know when something is done. If we write a chapter on arrays, how would we ever know it is completed? TC: In support of Mara's point, our documentation is laid out a bit like this already. If you look at the Reference, there is organization about grammar and types. Then we have separate libary documentation that also includes many opsem details (which are also covered in the Nomicon). This is what we would expect due to [Conway's Law](https://en.wikipedia.org/wiki/Conway%27s_law). Mara: Yes, this matches kinda what we already do. Move away that the grammar is the most defining thing of a language. Connor: Not sure it quite matches a full, complete phase separation. e.g., arrays. It is not separated out by type system, but rather types. The reference is closer to what he is envisioning with the spec. Pietro: In the end, the most important thing is to pick a structure and go with it. We can continue to discuss for months and still end up at the same place. Ok with going with Mara's proposal. Especially if going to start from scratch we need to get moving forward. TC: Another note of support with Mara's point. We perhaps shouldn't accept as given that other specs focus first on the grammar and that everything revolves around the grammar. There are specs (e.g. [r7rs](https://small.r7rs.org/attachment/r7rs.pdf)) that are organized about different concepts that are important to the language. pnkfelix: Memory is that is more like a phase separation. TC: It has, e.g., a separate section for types, discusses separately what we would call operational semantics, etc. Mara: Looking at the [Boolean](https://doc.rust-lang.org/stable/reference/types/boolean.html#boolean-type) section in the Reference. Put the information that is likely to be the next question closer to each other. Joel: Make it more amenable for teams to write. pnkfelix: It would make it more clear for various teams on what they are responsible for. But we should choose something that allows us to make progress. Connor: Mara's point is presupposing which questions will be asked. But it depends on who is using the spec. Joel: We need to pick a lane pnkfelix: Heavy cross-referencing. Mara: Not convinced that the common model for specifications are the right way to go. Connor: Implementers might like it top to bottom for one feature. pnkfelix: But we are not writing the spec for implementers. Pietro: Assume cross-linking will be presenting. All loops link to the loops section. There is not going to be a reprsentation that will satisfy everyone. On the other hand, for the purpose of safety critical, it might be nice to have everything in one place. But that is a nice to have and not a hard requirement. Mara: If we were moving entire sections from the Reference or Ferrocene, we cannot tell how complete or incomplete these sections are. The current proposal will allow us to check and track what things need to be done to make things complete. Connor: Doesn't think it is necessarily true that you can't tell if something is complete; you would still need to know if something met all the phases. pnkfelix: Consistency between the sections is going to be key. Joel: We need a concrete list of chapters that fit into Mara's proposal. pietro: Port the sample chapters into that structure, as well as Ferrocene and the Reference. Joel: Will work in Zulip to find a time where we can all get together and try to lay out what the chapters are. **While there was vigorous discussion and some disagreement, there was general consensus in the end that we move forward with Mara's proposal and we will now work with that is that plan of record.** ## Any other Business Set up an off-time special meeting to discuss high level structure and chapter layout for Mara's proposal.