---
title: T-spec meeting 2024-01-11
tags: ["T-spec", "meeting", "minutes"]
date: 2024-01-11
discussion: https://rust-lang.zulipchat.com/#narrow/stream/399173-t-spec/topic/Meeting.202023-01-11
url: https://hackmd.io/KqDSbI9tSI6pfMppiba1vg
---

Attendees: TC, Eric, Joel, pnkfelix, Connor Horman, Pietro, Lukas Wirth, Mara

## Sample topics

Joel: https://github.com/JoelMarcey/rust-lang-spec/pull/1

Connor: https://github.com/rust-lang/spec/issues/12

Mara: https://htmlpreview.github.io/?https://gist.githubusercontent.com/m-ou-se/529e3db782a0ce8ecd5043cc0adfa4af/raw/0f982c83e5733a72ec0eff6c285a48d1f5e839e4/draft.html

^^ TC: Is there a link to see the source of this one?

Mara: source: https://gist.githubusercontent.com/m-ou-se/529e3db782a0ce8ecd5043cc0adfa4af/raw/0f982c83e5733a72ec0eff6c285a48d1f5e839e4/draft.html

TC: Thanks for that. More specifically, was it drafted directly in HTML or is there some tooling being used to build that?

Mara: no tools other than vim ^^' (for now.)

TC: For comparison, the Rust reference:

https://doc.rust-lang.org/reference/types/array.html

TC: And the FLS:

https://spec.ferrocene.dev/expressions.html#array-expressions
https://spec.ferrocene.dev/types-and-traits.html#array-types

Joel: initial impression: Connor's is straight to the point .. spec.. very matter of fact. like the step-by-step approach.

Joel: Mara's is explanatory. like the way the formal/informal notes are laid out

Mara: The yellow notes in my draft should be optional/hidable.

Felix: ascii based grammar vs something more visual (like mara's draft).

Mara: The input would still be ascii, but the output could be nicely rendered.

Joel: Noticed that most language specs don't have a full well defined grammar.

Felix: Really like the version note in mara's draft.

Mara: same thing for editions.

Eric: Tracking *versions* is tricky, because they don't usually add whole sentences, but modify parts of it, etc.

Mara: Yeah, tracking editions is more important, versions is too much work, but we could add informal notes on versions where very relevant.

Pietro: with a version just get the spec for that version.

TC: We fix bugs with breaking changes that we check with crater runs. Those are often not documented before. Often fixing those is wha might cause us to document them.

Mara: Maybe we should include version things only for breaking changes, that change behaviour. not things that just don't compile before.

TC: Perhaps for comparison, we should look at the FLS. It achieves being a bit more concise by being more compositional.

Mara: There's a bunch of information that's not there. The links go into the glossary.

TC: Joel's draft reminded me of Rust Reference. To what degree are we not just extending the exiting rust reference, if we went with that style?

Eric: Would be good to combine the existing information (incl. rust reference). makes sense that it looks similar, as there is a lot of overlap.

Felix: Eric: do you see significant improvements?

Eric: Especially like Mara's presentation.

Eric: In general, more structured information is good.

Eric: Different approaches in kinds of information to present. E.g. how ferrocene spec has "legality rules" and connor's has "constraints".

Mara: I find it really important that you can just jump into a spec and read a small part of it, and still get the correct and clear information.

Connor: Having such terms/secitons can help with that.

Example from cpp lib: https://eel.is/c++draft/structure.specifications

Mara: Agreed, just saying that this property is really important and we should keep it in mind.

Pietro: for us (ferrocene spec), it was very useful to put all UB in their own section, to collect it all into one page.

Mara: I named every single rule/paragraph, which really helped me structure it with just "one fact" per rule.

Felix: I really like that, but we should consider the stability and maintainance overhead.

Joel: Are we converging to Mara's pressentation?

Connor: Not convinced on labeling every clause. More useful to link to sections and have numbered clauses.

Mara: We don't need to have label for every single sentence, but every independently consumable fact should/could have.

Joel: Named paragraphs feels more flexible. We can just move them around.

Pietro: ferrocene spec has 4700 paragraphs.

Pietro: you need stable identifiers if you want to link to it. links will be broken for a language that changes as much as Rust. so either do mara's approach, or use a random id.

TC: To what degree are we reacting to the fact that the labels are shown? We could of course have defined labels for each section (that we manually maintain) without making those labels visible.

Joel: I like the labels being visible in the left margin.

Connor: I like having the labels visible.

Mara: We should ask the stakeholders on their input on the drafts.

Pietro: also include existing texts?

Mara: Yes, absolutely.

Mara: So we give them the five docs, and ask for guidance/input.

Connor: With my stakeholder hat, i like Mara's presentation, but a bit more.. rigorous.

Joel to handle the stakeholders.

https://blog.rust-lang.org/inside-rust/2023/11/15/spec-vision.html#stakeholders

Mara: Let's make sure to not just ask which one people like best, that's not very useful. We want feedback on which parts are or aren't useful to them guidelines on how to continue.