T-spec meeting 2025-11-20

--- title: T-spec meeting 2025-11-20 tags: ["T-spec", "meeting", "minutes"] date: 2025-11-20 discussion: https://rust-lang.zulipchat.com/#narrow/channel/399173-t-spec/topic/Meeting.202025-11-20/ url: https://hackmd.io/pAkxVCilQtCw9RGDlAi-AQ --- # 2025-11-30 - `t-spec` Meeting ## Attendance ### Attendees - TC - Eric Huss - Jack - Pierre-Emmanuel Patry - Sid A - Tomas - Pete LeVasseur - Josh ## Agenda ### Niko's document https://hackmd.io/EqZLWav6Si2C44ickZJLvQ #### Vibe checks and thoughts Please create an area with your name and add in thoughts. Questions to address * Points you feel are particularly good or important to you? * Are there missing points-of-view (e.g., something treated as consensus that is not in fact consensus, or just incomplete coverage?) * Which of the questions raised are particularly important to you and what do you want to share about it? ##### nikomatsakis Nothing to add, I wrote the dang thing. I guess I will say one thing which is that, while I would like to see a lang-docs/contributors team, I also do not (any longer, at least) believe in the "create a team then fill it" style of working, I think the challenge there is to go and find people and see if we can engage them to do the work. Or consider contracting, I'm not sure. Whatever it takes. I suspect we'd find that a lot of people might really enjoy it though. ##### TC ###### Good document Thanks to Niko for writing this up. It sounds representative to my ears. ###### Supply/demand > ..but I believe strongly we can engage (or hire) tech writers... In the context of the recent discussions on funding maintainers, I think a lot about the supply/demand curve for the Project. There are places where we are good at bringing in people with the skills and willingness to do some kind of work (and to have staying power in doing it) and there are places where we are less good at this. For technical writers and editors, this is somewhere we struggle, and I do think that hiring for this would add value. We've recently clarified our Project budget situation for 2026. Perhaps this is a thought there. ##### Eric Huss Eric: It didn't address what the Spec team would be doing / is doing / what its purpose is. The document didn't address the problem of "QA" for lack of a better word (or "specification support"?). Many changes come in without sufficient clarity or completeness. There's this kind of gap between some contributor wants to stabilize some change to getting a completed set of documentation changes for the feature. Currently there really isn't support for that gap. The reference reviewers are often the only ones who have to support that, which is a large time investment. Sometimes changes aren't as they actually are described, or there are significant flaws or oversight that was not previously identified. ##### Pete LeVasseur > This is me riffing, but I believe strongly that open PRs are an energy drain. Being able to land content and establish a to-do list is a very big win. I'm a bit conflicted on this: Yes, it definitely can become an energy drain, but we should clarify: an energy drain on who and at what stages? It may become a bit of a challenge to maintain multiple somewhat duplicated sections and have them be noted as applying to unstable or in-flight features. The energy drain on the contributor could be lower though. ##### Sid Askary A Spec that is pegged to a particular compiler release (similar to FLS) - call it **RBS** as in Reference Based Spec - would also be helpful and can serve as basis for LTS, among other things. Sid: Long term support could be income-producing for team members. Get paid providing support for broader communities. ##### Tomas It seems, with all the fantastic work that TC and ehuss are doing that there is a significant bottleneck there, and it'd be good to address that somehow. ##### Josh Triplett Vibe: I think this captures many points of view and many issues. I think there are number of desirable requirements for a spec that it doesn't capture, though we can iterate on that: - Cross-referencing compiler tests vs embedding tests directly in the document - Tension between: Is this a good example or is it a good test? We treat them the same in the document but a good test may not be a good example at the same time. - More detail on the idea and value of incremental addition and improvement, and collaboration within the document. It's important to be able to coordinate. - An advantage of "unstable text" is that we can then use that to separate the approval process steps. For instance, the "unstable text" should be approved by individual topic-expert teams (e.g. T-types, wg-const-eval, ...). Then, later, editorial changes can go through the editorial team. - But also: editorial changes are something that needs a feedback loop through the topic-expert teams, on the basis that editorial changes *can* change semantic meaning, or can conflict with further intended semantic work. - Value of the document as a QA tool for validating Rust compiler code, including corner cases and discrepancies in the compiler implementation. This is implicit and should be explicit. - We need a triage process to "steer" things towards the right topic expert team - Need an explicit process for "stabilizing" text Also, as a note: I have a document in progress (not quite ready for broader consumption yet) proposing some concrete process steps/improvements and structural steps I think we should make. Will share as soon as I get it slightly further in shape. But structurally it has a *lot* in common with this document. > Recommendations and conclusions I think there's a missing detail here. You say: > I approve of the concept of the lang-docs team as editors. I also think the teams should be the ones tasked with judging technical accuracy. I think we should be clearer about how we delineate who is approving of what. But this document doesn't talk about how we fix the "team of two" problem, nor does it talk about the tension between T-spec (as the team responsible for "make there be a spec for Rust") and lang-docs (as the team this recommendation describes as editors). > We should form a lang-docs/contributors team This feeds into the same matter: I think there's a question worth considering here, of the structure of "writing the document" and "approving changes to the document" and "doing editorial work". By way of example: should we form a lang-docs/contributors team, or should we have T-spec be the "contributors" team and transform lang-docs/reference into T-spec/editors? (And, in the future, hire professional technical editors as part of the editoral team.) ##### jack Summary: I think generally the document covers the different viewpoints. It does lack some *details* (see Josh's vibes), but seems good as an *observational* document without discussing solutions. * Needs of "Alternative toolchain vendors" were not elaborated on >For it to do this, we need to address (first) the gaps around completeness and (second) the integration of the reference into language processes (and addressing the reality of limited maintainer bandwidth). I maybe disagreee with this - completeness will *always* be a moving target, and if we don't get integration into language processes, I'm not sure we can reasonably reach it. It's much easier to incorporate *new* things than existing things. (Especially, because the existing things will be "backfilled" as needed to be able to document the new things.) > Advanced Rust users and Rust learners who prefer a reference style, who wish to understand what a particular feature will do. I think this *should* be an explicit target. > When it comes to the normative content of the reference, the lang/types teams are the ones that make the decisions that determine what the reference should express. I think this also includes the requirements-setting, for things like the balance between readability and formality, for instance. > Updating the reference is often a kind of "afterthought" and the lang-docs team members expressed fear that permitting people to land draft or low quality changes into the reference would reduce the incentive for people to improve the quality of those changes, particularly if draft chapters were sufficient for stabilization. This seems like it rhymes with various concerns expressed in many Open Source projects. There is a continuous balance, between "get people to clean up technical debt in the area" as a condition of getting code in, and the barriers to entry. I don't think people are expressing that that tradeoff is not real, just that the current point/balance selected in that tradeoff is not working. (And as noted elsewhere in this document, I think *some* of that root-causes down to "there are only 2 team members and too much work for 2 team members".) > For the types team in particular, English text is a difficult medium to use for the reference. The types team has largely decided not to use the reference as their normative text and has a preference for something like a-mir-formality. This seems like something that depends on those tradeoffs between formality and readability, where if we want to go this route, it would help to get much more detail on the advantage of a-mir-formality (over using Rust), and how readable it is for folks. ##### pierre-emmanual patry > Mathematical notation that must be learned can be a challenge for this audience Could we introduce some "railway like" notation (different from railway) to help with this ? Would this even be worth it ? A simplified representation does not feel like it aligns well with the intended audience. > The expectation is that the spec will be integrated into the stabilization process. vs > The Rust reference tracks rust-lang/rust/main It is not clear how conflict free would be this two part contribution. One part seems to embrace nightly features and the other does not. > The question of what it would mean to be a "conforming Rust compiler" is a broader one, and thus the spec only defines a small part of it: specifically, what Rust programs should do when compiled. This is probably too broad since the spec also defines a subset of rejected rust programs and not only valid ones. TC: You'll be happy to know the Reference does have railway diagrams, we added them many months ago. PE: I was referring to some other ways to simplify mathematical notations akin to the railway diagrams added a few month ago. Josh: As in - "ebnf: railway diagramgs" - "other notation: more-acessible-version" #### Discussion Potential discussion topics * What *is* the role of the spec team * Requirements and role of the spec * Target audiences correct? (Notably advanced Rust users) * Incremental landing of PRs * Hiring of technical writers ---- ##### Q: What is the role of the spec team and requirements of the role Niko: To shepherd this process to get these needs met. The needs I identified early on. The Reference and FLS are how we do that now, that could change. The team was commissioned to implement this RFC. Niko: Re, target audience, where exactly do advanced Rust users fit? I see two versions: (1) The reference is limited in scope and serves the behaviour of the language. (2) more broader, guide-like thing. Niko: Both have values. A narrow Reference has clearer scope. A guide-like could be more accessible, show our philosophy. TC: Originally it was writing a C/C++-like specification. That ceased to be a current goal. But there's a plausible goal for someone to pursue this. If someone's willing to provide the financing and see this valuable, there would be value to doing that. Without that, I see the role of the Spec team to resolve this disagreemend and then I don't see an ongoing role of the Spec team unless we take on other responsibilities. TC: Target audience is the Project itself. The Reference should support the processes of the Project. Delineate the scope of the Lang team itself and being relatively isomorphic with that scope. When the Lang team changes the language, that should imply changing the Reference and vice versa. Therefore it's the Lang team call or them delegating it to someone else. This amounts to defining the Rust language. Our jobs on the lang team is to define the Rust language and writing it down is a good way to define the language. So we should be writing that down. TC: Incremental landing of PRs: there's a deep relationship between work we want (nightly things, partial work) that depend on the involvement of the teams, integration of the processes, questions like having a technical writer. A lot of interplay there. It's difficult to answer separately. I was hoping to do it incrementally. TC: Hiring technical writer: yes! Eric: I think the Spec team's role mostly ended as we decided to not move forward with the "from scratch" approach and moved to the two documents we have now. The Spec team doesn't have a work product now. Eric: I have a WIP for defining the audience for the Reference. I don't think there was a huge disconnect between what Niko put here. Niko: What's your take on advanced rust users vs. rust team members. Is that important? Eric: What serves one can often serve the other. As long as we have thins that are somewhat accessible, that helps both sides. Someone's trying to understand some aspect and a formal definition works for them, great. If they need a more higher-level that's useful for them and other less technically minded contributors. Niko: Where do you see the scope. Narrow-minded vs. broader? Eric: I think it should be very focused on the language. It's too broad of a scope to try to go beyond that. I've written down whaht are clear boundaries of what constitutes the language. Niko: That's awesome. I'd love to read that. Sid: I appreciate Eric and TC's work on maintaining the Reference. You guys are so careful and you review things and put things in very deliberately. But there is a need for a moving spec. Need for docs that mimics the reality of what's happening in the compiler particularly. When we were working on the editions, the contributers are the compiler people. This spec team is currently aligned with the work product coming out of the compiler. The lang team defines the language, but there is the notion of solidifying, maturing the language. The lang team says what new features and changes are going to happen. But given the 10 year history of the language, a lot of the work will be reverse-engineering what's happening in the compiler. I'm hoping that we keep building the document that describes the reality of the language. Not to dissolve this team. Sid: The reality resists in the compiler. When the behaviour is disputed than Compiler and Libs need to resolve that and define the correct behaviour (and document in the Reference). Josh: The lang team owns the idea of defining the language. The lang team chartered a spec team to make there be a spec, and so one role of the spec team is as the delegated team responsible for making there be a spec for the language. I think there's a fundamental tension there, where lang previously delegated to lang-docs the task of maintaining the reference, and T-spec identified the reference as part of its strategy, and that immediately created a tension. And one way we could resolve that tension would be to say "well, the team responsible for making there be a spec has selected the reference, and there's a team that owns the reference, so we're done". I think that would be inappropriate, and I think that would be abdicating T-spec's responsibility to *make there be a spec*. Relatedly, in the course of the work of T-spec, I think we've identified substantial maintenance challenges and process issues with the way the spec is maintained. Niko's document captured that from many points of view and with a great deal of empathy. I think we need a team responsible for coordinating amongst the teams of experts who own the topic areas, and amongst the editors, and taking responsibility for making there be a spec. And I think it makes sense for that team to be T-spec. Jack: The role of the spec team goes beyond the reference. We've now said that the FLS is part of that store. So there's more to this than just making the Reference accurate and complete. We should always be listening to people who need the spec. The Spec team's job may not be writing anything, but it's ensuring we're listening to people and incorporating that into the product. Jack: I hear Sid's comments on the compiler being involved. But I think that's more making sure the Spec team works with other teams to integrate making sure the spec integrates with all the teams' processes. I want to make sure that we have a team that can evaluate the situation. Jack: Re target audiences, we have two different documents with different target audiences. I don't necessarily agree the target audience needs to be the Project. I think one of the reasons the Spec team was chartered was because companies and users need the spec. I don't think its' for learnability. People need it so when they write a tool, compiler, program to have a place where they can go to know exactly how the program's going to behave (a place that's not the rustc compiler). The goal should be to let other people use the language completely and fully. I don't think we should focus on learnability. The normative version needs to be precise and that may be at a cost of learnability. *** Niko: I'd like suggestions on what we should do next. Josh: Jack said this is a good document describing the problem but without concrete proposals. The next step is to start talking about what we see as potential solutions to the identified problems. It might make sense to identify 2-3 different categories of potential solutions and have people who think these are appropriate solutions to collaborate on them. TC: I want an answer on the question of whether there's an urgent problem to solve or not. I said in the previous meeting to give us some time. Eric's writing out a PR that would describe the scope and document the view of the current maintainers. To give a basis reasoning about this. Writing down the process about writing down the language can help us build the language. TC: The answer to whether there is an urgent problem will inform the next steps. If there isn't an urgent problem, then give us some time. We do have the project goals that we're working towards. Josh: Niko's document described what I think are urgent problems. I'd like to see more direct responses for the things that are addressed there. I think we need to respond to those in some meaningful fashion. TC: We're writing the preface for the good of the readers. Niko: TC, my take is it depends on the definition of urgent. The PRs are moving forward and they aren't 100% blocked. There are structural issues in the Project that we need to solve. That feels like an important problem to me. There is some urgency and I see this as part of the Spec team's work -- to help bridge this gap and figure it out. Niko: I like what Josh suggested about reviewing proposals. A part of the role of this document is to serve this Project. I'd like to get the voice of other Project members. How would they like to make use of the Reference? When talking to people I never had anyone say "I really love contributing to the reference". TC: The Reference is not alone in this (easy, fun to contribute to). Writing RFCs is hard. Contributing to the language is hard. Contributing to the compiler is hard. All of these can stand for a lang time. We do sometimes let large PRs hang. We are under capacity. So is the Lang team. So are the other teams. What is the standard for this and how does it differ from the standard for the other teams. Niko: What is the goal we're trying to achieve. In what timeframe? Do we thing we're going to make it? I think there is a problem but I don't think the lang-docs team is the problem. Maybe it's helpful to get a clearer picture: how fast do we plan to get to the level of completeness. And will we get there? Niko: But I'd also prefer to frame this less combatively. Can we be brainstorming and discussing alternatives while we also make progress on the PRs? Hopefully we land on a few concrete changes we can do and try them out. When the Oli came to the Lang team and said they were concerned because they didn't like interacting with the lang team, Tyler and I sat down with him. Doubling down on the champion process was what came out of that conversation. We can do other improvements but it's important to address this. Josh: About the question of "at what point do we see the question as urgent", what standard should we be setting? We could identify how much work it takes to write an RFC, get the change accepted, getting the change to the compiler, writing the reference. And how people feel about that. And we should come up with a concrete plan and then setting a timeframe for solving an identified problem. If the problem is we're not clear whether there's a problem, let's focus on that and resolve that problem. TC: I feel you're pushing it into a black-and-white framing. I resonate more with what Niko said. Let's talk about what we want to achieve and what's the timeline for achieving it. You mentioned that it's a problem if people contributing to the referenece are saying that it's the hardest thing of making a change. I'm sure some people feel that way. But are these representative? Are their reasons accurate? I resonate with what Niko said about the Lang team: Oli reached out, we had a discussion about it. Josh, you're representing this most acutely, we have had a lot of discussions about it. I agree the concerns are valid, we want to address them. We're now creating another book about reference contributions. We're doing office hours every week. Eric: How can we identify what the problems are? Niko's document has a bunch of observations. The bandwidth limitation is an obvious problem without an obvious solution. It's not solvable if people aren't willing to contribute. Can we engage this process problem more with the lang team? The key part is the gap with the lang team. For example, Lucas's contribution -- TC and I were the only ones responding to the change. Someone else on the Lang team could figure out what is the language change, figure it out clearly what it does and how it's reflected. This is frustrating for Lucas and us as well. Can we talk with the Lang team about smoothing out the process? We have a QA gap: a contributor comes with a change, then nothing happens, then TC and I came to figure out whether this is actually describing the change correctly. If people can come in and help, that would be massively useful. Sid: I understand there are issues with Lang and everything. I think it merits discussion outside the Spec team. I'd like to focus on RBS. One way to make this wokr is to continue working on this. I'd like that methodology to continue and bring more people to contribute to this and sync periodically with the Reference. And continue contributing. Niko: I'll follow-up on Zulip. Josh: We've had 15-16 hours of meetings and trying to getto a resolution. I've little hope more hours would help us resolve it. Let's find a different way to find a resolution. Eric, I sympathise with your position. But Niko's doc and my proposal is very much gearing towards having other teams to help and a lot of them are interested in it. I think there's a lot of people willing to step up but maybe not do the work in the same way as the lang-docs team did this. Niko: We're still debating on whether there's a problem. Eric I like your suggestion and I think it aligns with the Josh's desires. We should talk to the Lang team, say that this isn't helping and we need to talk about that. I'll follow-up with you on that. I want to understand Sid's situation. Josh, I'd love to see your proposal floated on Zulip. I'd like to work towards a design document and discuss it with the lang team. Next week is Thanksgiving, I propose we meet the week after that.