T-spec meeting 2025-07-10

--- title: T-spec meeting 2025-07-10 tags: ["T-spec", "meeting", "minutes"] date: 2025-07-10 discussion: https://rust-lang.zulipchat.com/#narrow/channel/399173-t-spec/topic/Meeting.202025-07-10/ url: https://hackmd.io/z7Kn4zV-SMyJVUvJyW1k7Q --- Meeting URL: https://meet.jit.si/rust-t-spec Attendees: - Joel Marcey - Tomas Sedovic - Eric Huss - tshepang - Pierre-Emmanuel Patry - Sid Askary - Jack - TC - Alex Senier - Josh Triplett - Pete LeVasseur - Yijin Yu Regrets: - Niko Matsakis Notes: Tomas Sedovic Agenda: - Updates to the agenda? - H2 2025 Project Goal Review: @joshtriplett - PR Review: @TC0 @ehuss ## Updates to the agenda Tomas: I'll be out from: 2025-07-14 (Monday) to 2025-07-17 (Thursday) next week, going to miss the next Spec meeting. ## H2 2025 Project Goal Review Josh: I've been putting together a 2025 H2 project goal to cover the possible improvements to the Reference. To cover more areas where there were potential gaps previously. https://hackmd.io/x74Z8l3GR-a0qUZdwUaQ3Q Josh: Talks about the Reference and how it's a critical peace of Rust documentation. Dives into the gap analysis. Mentions five areas of potential gaps (based off discussions with TC, Eric and others): Type inference, the new trait solver, more details on macros and expansion, name resolution, const eval. Proposal: let's have a number of established Rust developers working on these and provide review bandwidth to make sure we don't throw a huge amount of content on the couple of folks doing review. Includes people who we're expecting to do contributions and mentoring from. TC: Thank you for putting this together. This all sounds great, but I would reword the design axiom a bit. There are cases where the Reference tries to tread carefully in certain areas around not making stability guarantees. What we've done lately is document the limits and what is not necessarily a stability guarantee. Josh: I intended to phrase it as the new material shouldn't necessarily intend to provide a stability guarantee. I'm hearing the nuance. TC: The thing that limits the lang team is where people rely on something to such a degree that when we try to change it, we're bound by all the people using it. That can happen even without it being documented. But when it's documented in the Reference that can provide a stronger basis that this is OK to rely on by third party code, and that can create more reliance. Josh: I'll rephrase it to make it more clear. Eric: I think it'll be challenging to thread that needle because the default is that everything is a stability guarantee. I understand it with things like type inference, but some of these goal items (like const eval) -- generally that's documented in a way showing what's stable and guaranteed. Josh: That's fair. I was thinking on e.g. when we're writing docs on type inference, the only thing that's normative is what the Rust compiler infers and that it can infer more but never less. For macros and expansion I'd expect the implementation details to be not-normative but what the compiler can do to be normative. Eric: Can you clarify what you mean in terms of name resolution? My intention is for it to be completely normative. Josh: Aspects of name resolution that talk about how you reference names in the namespace are likely to be normative. The aspects that get into things like "here's how macros are backreferenced / can generate other macros" -- that's something where the current behaviour is relied upon but we also don't know what people are relying on and so we just do a Crater run. So this is more about it being hard to know what people rely on until we make a change. Josh: In theory any stable behaviour of Rust is a stability guarantee because people may rely on it. But in practice we rely on Crater. I think the Reference can be similar in that we can make changes if no one relies on them. I want to describe how things work without necessarily creating stability guarantees. We'd start documenting everything and then figure out what to guarantee later. Pete: From the safety critical point of view: I don't know if there's any official policy on the Reference right now around this. There was a text that turned normative at some point. Is there a way to tag something as being / not being normative? Josh: I suspect there are sections that have explicit tagging. We'll go over the Reference and see how it's done so far. TC: How practical would it be to start with places where we really are sure about the behavior? That might be an easier place to document first rather than being really exhaustive. From the editorial PoV sometimes when you're trying to be exhaustive, in terms of documenting everything the implementation does, it can be difficult to write down and describe that clearly. Josh: It's certainly possible. But on some of these I thought of approaching it by documenting it all and then shortening it down. This is one of the things that stalled down the Reference in the past. But in other areas we may have a good idea of what can be stabled and in that case we should do it. I just don't think we should do it at the expense of showing what's documented. Josh: Not disagreeing, more "if that's how it happens to work out, that's how it works out" but if it doesn't, we can adjust it later. TC: I'd want to communicate a sensitivity to the editorial aspect of the Reference and the review bandwidth. E.g., and I know this isn't what you're doing, someone could take an LLM and point it at `probe.rs` and then provide a really comprehensive and (let's say) correct description of what `probe.rs` does. We'd get a PR that would be really comprehensive and correct but it'd be a PR that we would never merge in the Reference. Josh: I appreciate that. If we went down the road of documenting every single thing the code does -- as opposed to documenting the endpoints, I agree. But I'm hoping that if we're being more flexible about non-normative areas, we can get approve and merge things more quickly. Historically, things often stalled out on the normative word. Eric: I'd have to see what it looks like, but I think this makes sense. Eric: Currently, we have a process where e.g. lang issues would pick up "this needs to update a reference". By my feeling is that changes e.g. to the type inferrence might get updated without the lang involvement. Josh: That's fair. Several of these things are more on T-Compiler rather than T-Lang. These things often get noticed only when they hit a surface area. If we're accurate about what we mark as normative or stable surface area, it's likely that would come across the lang's desk (due to crater runs etc.). And vice versa if we see a Crater run could be a signal that we should update the Reference to make things more normative. Josh: But on the non-normative side we should keep Reference in the loop of some of the processes. Jack, do you think it'd make sense to start the discussion with the compiler around this? Jack: I don't want to speak on behalf of the Compiler team too much. On the type thing, I think it's reasonable for me to say we can incorporate any changes being to considered for a change to the Reference. This is something where we can look at e.g. test changes and seeing if that requires a Reference change. But it's going to be difficult to figure out changes rather than ??. TC: On the question of "what needs Reference changes", you look at the Reference and answer "does the Reference cover this?" or "does it say something other than the PR does?", and if so, then it needs to be updated. If it says something close to it, then it probably should be updated. Otherwise, while it would be good to document, it doesn't necessarily need to be. When in doubt, ask Eric or myself. Josh: I agree it's probably easy when people think to do it. The harder part will be for people to get into the habbit of checking the Reference in the first place. TC: That gets to my second point. I don't have process concerns on the lang side because we block PRs until the Reference changes happen. To the degree type system behavior is in the Reference, the types team will need to similarly block PRs on this. What surprises me, in what you're saying, is the suggestion that things that are entirely in compiler's domain would require normative changes in the Reference. What would be some examples of that which wouldn't land on our desk on lang, or on the desk of one of our subteams, types or opsem? Josh: I wasn't explicitly saying "normative" changes. Sometimes it's not clear whether it's normative or not. But I was thinking of changes that could affect the non-normative text that nonetheless we might want to change. TC: OK, what kind of non-normative content do you have in mind that would require such chanegs? Josh: There may be negative things in the reference: "here are things the compiler can't do". I suspect that if the compiler lifts that limitation, I would expect that that limitation sholud go away from the Reference. TC: If there were some limitation that were lifted, and it were visible on stable Rust, that would have to go through lang. Josh: I wasn't talking about visible areas but something that was never possible but now due to a compiler change could be possible now. An implementation change rather than a language change. Josh: As I'm working on the macro attributes code, I'm finding areas where you can't write a macro by example due to a deep spaghetti code inside the compiler. That's a thing we could plausibly document but also hope to change in the future. TC: The editorial guidance I'd give here would be that we have the Reference and the Rustc Dev Guide. And some of these things sound like they should be in the Rustc Dev Guide rather than in the Reference. Josh: I'll take this to consider and it may well be we'll find things that are better suited for the Rustc Dev Guide and submit them there. But there are details that we think does have a place in the Reference where we could say "here's why it's the case why we can't forward-reference a macro" etc. Sometimes those limitations are things that commonly arise and people ask for them. For these, a mention in the Reference may make sense. TC: That makes sense, as a design rationale perhaps, but it just occurs to me that there may not be a lot of places where that would be justified. Jack: I think anything that is an FCP probably should have something in the Reference that sholud be updated. Things in the compiler.. maybe. Maybe something like flags. Josh: Given that FCPs are mostly used for one-way doors that involve changes about stability and similar. What types of things does the compiler team uses FCPs for. Jack: Compiler flags, changes to JSON output, tier 1 targets include the compiler. But generally it's the compiler flags. Josh: Currently, the reference doesn't cover most of the things we've just talked about. But I imagine that might be useful in the Reference in a distant future? Jack: Yes. TC: There's also a separate document: The Rustc Manual. That covers the target tiers, rustc options, etc. Josh: Does everyone having any objections beyond the notes I took from this meeting (assuming the goal is accepted). (broad support from everyone) Josh: Summary: 1. note about stability guarantees 2. document what may or may ont be normative 3. document processes about making sure the Reference may need a change 4. looking at material that would fit more in the rustc dev guide TC: On the "giving the Reference a heads-up when a change needs to go in". It's more than that -- it should block the PRs on Reference updates. Josh: That seems like a good idea but it's outside the scope of me and the team. TC: From the Reference management side we need that to include the content. Everything that's in the Reference are things that can't change in Rust unless the lang team approves them. So the lang process covers what we need from the Reference side to accept the content. For content that might be outside of lang scope, we need compiler or other teams to have the same process. Arguably, everything that belongs in the Reference falls within the jurisdiction of lang (including delegated jurisdiction) and therefore lang's policy here regardless. Josh: I appreciate everything you just said in principle. I suspect that it's not quite as comprehensive as you're saying. That every change that goes to the Reference is going to go through lang. It's the case that they *should* do that, but they don't always do. We've made changes years ago that were not caught by the Reference. TC: When what you describe what happens, the process failure was that it didn't cross lang's desk even though it shouldn't have. In principle, everything that needs to be changed in the Reference should fall under lang's policy. That's the important bit. Josh: You're arguing that if there's something that's not in the direct purview of lang, that you'd like the team to verify that it follows the same process before you're able to accept that scope in the Reference. TC: That's why I'm mentioning this in the context of the project goal. Those discussions need to be part of the plan. Jack: My gut feeling is that the Types team is going be happy to update the Reference but that they won't be happy to block changes on the Reference updates (beyond say a week of waiting) before merging a PR. What is the review burden of adding these changes? Josh: Because of the possibility of the changes of iterating we're waiting for the changs to the Reference being merged until the underlying change is completely nailed down. Eric: It's hard for me to know whether a PR posted to rust-lang/rust is in the final for. The PR often changes before it's merged. It's a time commitment to write a documentation that can then change. Jack: I think the team would be happy to block on the content changes but not editorial changes. The "content" is what you'd distill the words for their meaning and "editorial" is how do you say the words. TC: I'd imagine indeed there would be push back on this. We have pushback on this on the lang side too. People find it annoying to have to wait before we merge the shiny new features people want. But if we don't do it that way, it creates some problems. If we merge a stabilization without the Reference PR ready, there are only two possible things that can happen next. One is that the lang-docs team rushes to make it ready before the beta cut. That's unsustainable. The other is that the Reference ships without matching the language. That's something we all decided we wanted to stop having happen. People say, "well, it'd be OK to merge as long as the author puts in a PR with the details, then the editorial matters can happen later", but this isn't the problem. When we're down to the editorial matters, we often do just approve it because we can then commit to merging it in time. No, the problem is that what people think is a complete PR often is not. Sometimes it's wrong or incomplete on the facts. Sometimes it's just too unclear to be able to tell at all whether it's correct and complete or not. Often it's not until you really start trying to clean it up, e.g. by adding examples and testing to confirm the behavior, that you can really even tell. Some percentage of the time, when doing this, the team (most often Eric) finds an error in the stabilization itself that we on the lang team missed. That's why these Reference reviews can take awhile, is that writing this down clearly requires understanding it clearly and completely, and that's just hard, and it sometimes uncovers that, actually, nobody actually understood it clearly and completely. It doesn't improve the Reference to start carving out areas where we don't do this. Jack: We should write the chapter to get changes in a place that looks good and then set up the processes that the Reference gets update. My preference is to make the chapter up rather than not updating the Reference at all. TC: I think it's important to get the PR up, but for content that's covered in the Reference, we're going to need to follow the process here. Jack: I disagree. We want to merge the PR and have the chapter up -- that's better than the Reference PRs becoming stale. TC: But if we don't follow the process, the Reference itself risks becoming stale. Jack: I don't want to wait on all the PRs until we've figured out the proceses. ## PR Review ### Question mark operator https://github.com/rust-lang/reference/issues/1927 - Should it be described in terms of the unstable `Try` trait, or just what implements `Try`? - Should we rename ErrorPropagationExpression? It's not necessarily about errors. (and I don't think anyone actually calls it that) ## Jitsi Chat https://hackmd.io/z7Kn4zV-SMyJVUvJyW1k7Q 8:02 J Josh Josh says: https://hackmd.io/x74Z8l3GR-a0qUZdwUaQ3Q 👍 8:03 PL Pete LeVasseur Pete LeVasseur says:Is the idea that the reference text is mostly normative, excluding where noted otherwise? 8:12 J Jack Jack says:+1 from me on documenting as completely as possible first and then going back and marking things with stability guarantees 👍 8:23 PL Pete LeVasseur Pete LeVasseur says:"in theory", "you could imagine" ;D 8:23 J Jack Jack says:On my end, I'm happy to have the types team be sure that we think about the reference when we make changes ❤️ 👍 8:27 Jack says:Rustc flags 8:33 me says:❤️ 8:45 PL Pete LeVasseur Pete LeVasseur says:Silence is golden~! 8:45 YY Yijun Yu Yijun Yu says:Sparrow Lii has also got interest in contributing to the goal ❤️ 8:46 J Josh Josh says:Yijun: Awesome. 8:46