From 7043c8a5835f06671178c547f995453ad11e5e70 Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Sun, 13 Jul 2025 12:16:19 -0700 Subject: [PATCH 1/9] Integrate the FLS into Documentation Processes Now that that FLS is an official part of the Rust Project and we can publish the FLS independently of dependencies required in the past, let's see if we can integrate the FLS into the documentation processes on the same level as the Reference. --- src/2025h2/FLS-integration-doc-processes.md | 78 +++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 src/2025h2/FLS-integration-doc-processes.md diff --git a/src/2025h2/FLS-integration-doc-processes.md b/src/2025h2/FLS-integration-doc-processes.md new file mode 100644 index 00000000..3dba5971 --- /dev/null +++ b/src/2025h2/FLS-integration-doc-processes.md @@ -0,0 +1,78 @@ +# Integrate the FLS Into Documentation Processes + +| Metadata | | +|:-----------------|----------------------------------------------------------------------------------| +| Point of contact | *@JoelMarcey* | +| Teams | <!-- #t-spec, #t-lang, #t-opsem --> | +| Task owners | <!-- @JoelMarcey --> | +| Status | Proposed, Invited | +| Tracking issue | | +| Zulip channel | #t-spec | + +## Summary + +Integrate the FLS into the documentation process [similar](https://rustc-dev-guide.rust-lang.org/stabilization_guide.html#documentation-prs) to how we have with the Reference, especially, but also other documentation as well. + +## Motivation + +The FLS has been graciously transferred from Ferrous Systems via the Ferrocene effort to the Rust Project. In H1 2025, a [Project goal](https://rust-lang.github.io/rust-project-goals/2025h1/spec-fls-publish.html) to bring the FLS in and publish a version under the auspicious of the Rust Project was successfully [completed](https://github.com/rust-lang/rust-project-goals/issues/265#issuecomment-3019529070). Let's now take this to the next level - ensure that we are treating the FLS as first-class documentation for the Rust Project, similar to how we treat the gold standard of the Reference. Just as the Reference is supposed to be updated in concert with language additions and changes, the FLS should as well. With the current combination of the Reference and the FLS moving towards an official Rust Language specification (whether as separate documents or combined), ensuring that they are as up-to-date as possible with existing language and `rustc` behavior is paramount. + +### The status quo + +The target audience here will be those that have a vested interest in the Rust Specification and want to see movement forward in ensuring that it is as much a source of truth of current behavior as possible. + +Keeping up with documentation is not always the most glamorous role for any project. And folks like @ehuss and others are doing an outstanding job at trying to keep the Reference current with actual code behavior. This is a hard job just for one document like the Reference. It will be even more difficult adding another core document like the FLS. But that doesn't mean we shouldn't try to make a process happen. As we try to integrate the FLS into a process where language changes require documentation updates to that doc, we can also look to see if we can streamline the process for the Reference as well. + +Without bringing the FLS into the official fold of documentation processes like the Reference, the FLS could end up being a dangling document, undermining the reason it was brought into the Rust Project in the first place. + +### The next 6 months + +Determine if the FLS can achieve the same [status](https://rustc-dev-guide.rust-lang.org/stabilization_guide.html#documentation-prs) as the Reference when it comes to documenting stabilized language features, where the FLS "must be updated, in full detail". + +The outcome of the next six months is variable. The entire six months could be investigative, with some prototyping. Or we could establish concrete processes for the FLS, possibly adjusting even Reference processes as well if it makes sense. + +### The "shiny future" we are working towards + +The shiny future we are working towards is to ensure that we have the processes in place to allow for the FLS and the Reference, our two documents that are attempting to normatively describe and specify the Rust language, to be first-class citizens when it comes to language updates and additions. + +Ideally, in my mind, there would be a requirement to have both the Reference and FLS updated as part of any RFC that requests a language feature or change. At the very least, both docs should be updated before a language feature or fix is stabilized. If there was a way we use automation to ensure this happens, maybe via CI or some other tooling, that would be icing on the cake. + +We don't live in an ideal world, so we may have to make compromises somewhere here, but let's start with the ideal and work backwards to something that could be acceptable to most people. + +## Ownership and team asks + +**Owner:** @JoelMarcey, in his capacity of `t-spec` team member will lead this project goal. + +| Task | Owner(s) or team(s) | Notes | +|------------------------------------|--------------------------------|---------------------------------| +| Discussion and moral support | ![Team][] [spec], [t-lang][] | | +| Adjust tooling, as needed | @JoelMarcey | Joel to find appropriate person | +| Standard reviews | ![Team][] [t-lang],[t-opsem], [bootstrap] | For any process changes, document updates and/or tooling integration | +| Continued updates for FLS releases | `t-spec`, particularly members from Ferrous Systems | | + +## Frequently asked questions + +### Why this Project goal? + +Short-term is to ensure the FLS is update similarly to the Reference upon any language changes or stabilizations. Long-term is to ensure that both the Reference and FLS are required to be updated before any language changes or stablizations are landed. + +### Can this be done in six months? + +Don't know. But we need to start having the conversations and see where it can lead. + +### Is this going to be too much process change for the Project to handle? + +Don't know. I am not sure what the actual changes are going to be required yet. That is a big part of this goal to find out. That said, we shouldn't let a potential disruption to process from keeping us doing the right thing? + +### Getting documentation updated is hard. Who would do that work? + +This may be the biggest blocker to making this goal successful. In order of preference on who would actually do the work: + +1. The owner of the RFC requesting language changes would also update the Reference and FLS as part of that RFC. +2. Members of the `t-spec` team could make the changes once they understand the technicalities of the RFC requesting the language changes. +3. Project volunteers who want to learn more about the language and compiler could update the documentation. +4. A hired technical writer + +### What happens if the FLS and Reference combine as one specification document? + +That's actually a potential outcome of the `t-spec` work in the future. So this may not be totally theoretical. Hopefully the processes we come up with are not so document specific that they can withstand such a merger. \ No newline at end of file From 1afd7770a97c755cbcb6e61ae472ed29cf26f070 Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Tue, 15 Jul 2025 19:23:16 -0700 Subject: [PATCH 2/9] Updated based on internal `t-spec` team feedback --- src/2025h2/FLS-integration-doc-processes.md | 44 +++++++-------------- 1 file changed, 15 insertions(+), 29 deletions(-) diff --git a/src/2025h2/FLS-integration-doc-processes.md b/src/2025h2/FLS-integration-doc-processes.md index 3dba5971..95378942 100644 --- a/src/2025h2/FLS-integration-doc-processes.md +++ b/src/2025h2/FLS-integration-doc-processes.md @@ -1,4 +1,4 @@ -# Integrate the FLS Into Documentation Processes +# Develop the capabilities to keep the FLS up to date | Metadata | | |:-----------------|----------------------------------------------------------------------------------| @@ -11,33 +11,27 @@ ## Summary -Integrate the FLS into the documentation process [similar](https://rustc-dev-guide.rust-lang.org/stabilization_guide.html#documentation-prs) to how we have with the Reference, especially, but also other documentation as well. +Develop the capabilities and capacity to keep the FLS up to date with the Rust language. ## Motivation -The FLS has been graciously transferred from Ferrous Systems via the Ferrocene effort to the Rust Project. In H1 2025, a [Project goal](https://rust-lang.github.io/rust-project-goals/2025h1/spec-fls-publish.html) to bring the FLS in and publish a version under the auspicious of the Rust Project was successfully [completed](https://github.com/rust-lang/rust-project-goals/issues/265#issuecomment-3019529070). Let's now take this to the next level - ensure that we are treating the FLS as first-class documentation for the Rust Project, similar to how we treat the gold standard of the Reference. Just as the Reference is supposed to be updated in concert with language additions and changes, the FLS should as well. With the current combination of the Reference and the FLS moving towards an official Rust Language specification (whether as separate documents or combined), ensuring that they are as up-to-date as possible with existing language and `rustc` behavior is paramount. +The FLS was graciously transferred from Ferrous Systems to the Rust Project. In 2025H1, a [Project goal](https://rust-lang.github.io/rust-project-goals/2025h1/spec-fls-publish.html) to bring the FLS in and publish a version under the auspicious of the Rust Project was successfully [completed](https://github.com/rust-lang/rust-project-goals/issues/265#issuecomment-3019529070). Let's now take this to the next level by ensuring that we can keep the FLS up to date with the Rust language in a sustainable manner by developing the necessary capacity and capabilities for doing so. ### The status quo -The target audience here will be those that have a vested interest in the Rust Specification and want to see movement forward in ensuring that it is as much a source of truth of current behavior as possible. +The target audience here will be those that have a vested interest in Rust specification work and want to see movement forward in ensuring that our documents are as correct and complete as possible. -Keeping up with documentation is not always the most glamorous role for any project. And folks like @ehuss and others are doing an outstanding job at trying to keep the Reference current with actual code behavior. This is a hard job just for one document like the Reference. It will be even more difficult adding another core document like the FLS. But that doesn't mean we shouldn't try to make a process happen. As we try to integrate the FLS into a process where language changes require documentation updates to that doc, we can also look to see if we can streamline the process for the Reference as well. - -Without bringing the FLS into the official fold of documentation processes like the Reference, the FLS could end up being a dangling document, undermining the reason it was brought into the Rust Project in the first place. +Keeping up with documentation is not always the most glamorous role for any project. And folks like @ehuss and others are doing an outstanding job at trying to keep the Reference current with actual code behavior. This is a hard job just for one document like the Reference. It will be even more difficult adding another core document like the FLS. But that doesn't necessarily mean we can't keep the FLS as up to date as is needed by its users. ### The next 6 months -Determine if the FLS can achieve the same [status](https://rustc-dev-guide.rust-lang.org/stabilization_guide.html#documentation-prs) as the Reference when it comes to documenting stabilized language features, where the FLS "must be updated, in full detail". +Explore options for developing the capability to keep the FLS updated with the Rust language, in a sustainable way, at the cadence needed by its users. -The outcome of the next six months is variable. The entire six months could be investigative, with some prototyping. Or we could establish concrete processes for the FLS, possibly adjusting even Reference processes as well if it makes sense. +The outcome of the next six months is variable. The entire six months could be investigative, with some prototyping. Or we could establish a concrete cadence and capacity for updating the FLS. ### The "shiny future" we are working towards -The shiny future we are working towards is to ensure that we have the processes in place to allow for the FLS and the Reference, our two documents that are attempting to normatively describe and specify the Rust language, to be first-class citizens when it comes to language updates and additions. - -Ideally, in my mind, there would be a requirement to have both the Reference and FLS updated as part of any RFC that requests a language feature or change. At the very least, both docs should be updated before a language feature or fix is stabilized. If there was a way we use automation to ensure this happens, maybe via CI or some other tooling, that would be icing on the cake. - -We don't live in an ideal world, so we may have to make compromises somewhere here, but let's start with the ideal and work backwards to something that could be acceptable to most people. +The shiny future we are working towards is to ensure that we have the capability in place to keep the FLS updated at the pace needed by its users. ## Ownership and team asks @@ -45,34 +39,26 @@ We don't live in an ideal world, so we may have to make compromises somewhere he | Task | Owner(s) or team(s) | Notes | |------------------------------------|--------------------------------|---------------------------------| -| Discussion and moral support | ![Team][] [spec], [t-lang][] | | +| Discussion and moral support | ![Team][] [t-spec], [t-lang] | | | Adjust tooling, as needed | @JoelMarcey | Joel to find appropriate person | -| Standard reviews | ![Team][] [t-lang],[t-opsem], [bootstrap] | For any process changes, document updates and/or tooling integration | -| Continued updates for FLS releases | `t-spec`, particularly members from Ferrous Systems | | +| Standard reviews | ![Team][] [t-lang],[t-opsem], [t-types], [bootstrap] | For any process changes, document updates and/or tooling integration | +| Continued updates for the FLS | Contributors from Ferrous Systems and others TBD | | +| Review of updates to the FLS | `t-spec` and contributors from Ferrous Systems | | ## Frequently asked questions ### Why this Project goal? -Short-term is to ensure the FLS is update similarly to the Reference upon any language changes or stabilizations. Long-term is to ensure that both the Reference and FLS are required to be updated before any language changes or stablizations are landed. +The goal is to ensure the FLS is updated sufficiently to meet the needs of its users. ### Can this be done in six months? Don't know. But we need to start having the conversations and see where it can lead. -### Is this going to be too much process change for the Project to handle? - -Don't know. I am not sure what the actual changes are going to be required yet. That is a big part of this goal to find out. That said, we shouldn't let a potential disruption to process from keeping us doing the right thing? - ### Getting documentation updated is hard. Who would do that work? -This may be the biggest blocker to making this goal successful. In order of preference on who would actually do the work: - -1. The owner of the RFC requesting language changes would also update the Reference and FLS as part of that RFC. -2. Members of the `t-spec` team could make the changes once they understand the technicalities of the RFC requesting the language changes. -3. Project volunteers who want to learn more about the language and compiler could update the documentation. -4. A hired technical writer +This may be the biggest blocker to making this goal successful. Part of this goal will be finding people who are interested in doing the work to author and review these updates or to find the budget to hire people to do this. ### What happens if the FLS and Reference combine as one specification document? -That's actually a potential outcome of the `t-spec` work in the future. So this may not be totally theoretical. Hopefully the processes we come up with are not so document specific that they can withstand such a merger. \ No newline at end of file +That's actually a potential outcome of the `t-spec` work in the future. So this may not be totally theoretical. Hopefully the processes we come up with are not so document specific and they can withstand such a merger. \ No newline at end of file From 49301d44f4ed3744188dfe8d1b877eaf94319d9f Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Tue, 15 Jul 2025 20:41:19 -0700 Subject: [PATCH 3/9] Rename proposal file --- ...ntegration-doc-processes.md => FLS-up-to-date-capabilities.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/2025h2/{FLS-integration-doc-processes.md => FLS-up-to-date-capabilities.md} (100%) diff --git a/src/2025h2/FLS-integration-doc-processes.md b/src/2025h2/FLS-up-to-date-capabilities.md similarity index 100% rename from src/2025h2/FLS-integration-doc-processes.md rename to src/2025h2/FLS-up-to-date-capabilities.md From 9c9c8013b629a6a4964cac80da1db85948455a0a Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Fri, 18 Jul 2025 09:58:19 -0700 Subject: [PATCH 4/9] Update src/2025h2/FLS-up-to-date-capabilities.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rémy Rakic --- src/2025h2/FLS-up-to-date-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/2025h2/FLS-up-to-date-capabilities.md b/src/2025h2/FLS-up-to-date-capabilities.md index 95378942..ad1f1d2f 100644 --- a/src/2025h2/FLS-up-to-date-capabilities.md +++ b/src/2025h2/FLS-up-to-date-capabilities.md @@ -5,7 +5,7 @@ | Point of contact | *@JoelMarcey* | | Teams | <!-- #t-spec, #t-lang, #t-opsem --> | | Task owners | <!-- @JoelMarcey --> | -| Status | Proposed, Invited | +| Status | Proposed | | Tracking issue | | | Zulip channel | #t-spec | From 03eedaf26151cfd4e9ccc9fbfbc516ebbf82488b Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Fri, 18 Jul 2025 09:58:32 -0700 Subject: [PATCH 5/9] Update src/2025h2/FLS-up-to-date-capabilities.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rémy Rakic --- src/2025h2/FLS-up-to-date-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/2025h2/FLS-up-to-date-capabilities.md b/src/2025h2/FLS-up-to-date-capabilities.md index ad1f1d2f..f0a632ca 100644 --- a/src/2025h2/FLS-up-to-date-capabilities.md +++ b/src/2025h2/FLS-up-to-date-capabilities.md @@ -39,7 +39,7 @@ The shiny future we are working towards is to ensure that we have the capability | Task | Owner(s) or team(s) | Notes | |------------------------------------|--------------------------------|---------------------------------| -| Discussion and moral support | ![Team][] [t-spec], [t-lang] | | +| Discussion and moral support | ![Team][] [spec], [lang] | | | Adjust tooling, as needed | @JoelMarcey | Joel to find appropriate person | | Standard reviews | ![Team][] [t-lang],[t-opsem], [t-types], [bootstrap] | For any process changes, document updates and/or tooling integration | | Continued updates for the FLS | Contributors from Ferrous Systems and others TBD | | From 4bde59177f488ab72bc75ec69014aab593ccdb03 Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Fri, 18 Jul 2025 09:58:40 -0700 Subject: [PATCH 6/9] Update src/2025h2/FLS-up-to-date-capabilities.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rémy Rakic --- src/2025h2/FLS-up-to-date-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/2025h2/FLS-up-to-date-capabilities.md b/src/2025h2/FLS-up-to-date-capabilities.md index f0a632ca..542c7445 100644 --- a/src/2025h2/FLS-up-to-date-capabilities.md +++ b/src/2025h2/FLS-up-to-date-capabilities.md @@ -41,7 +41,7 @@ The shiny future we are working towards is to ensure that we have the capability |------------------------------------|--------------------------------|---------------------------------| | Discussion and moral support | ![Team][] [spec], [lang] | | | Adjust tooling, as needed | @JoelMarcey | Joel to find appropriate person | -| Standard reviews | ![Team][] [t-lang],[t-opsem], [t-types], [bootstrap] | For any process changes, document updates and/or tooling integration | +| Standard reviews | ![Team][] [lang],[opsem], [types], [bootstrap] | For any process changes, document updates and/or tooling integration | | Continued updates for the FLS | Contributors from Ferrous Systems and others TBD | | | Review of updates to the FLS | `t-spec` and contributors from Ferrous Systems | | From 0eaeef2312f769642ebcd970a03bc68cf35cc9e2 Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Fri, 18 Jul 2025 10:02:35 -0700 Subject: [PATCH 7/9] Update FLS-up-to-date-capabilities.md Try to fix markdown errors. --- src/2025h2/FLS-up-to-date-capabilities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/2025h2/FLS-up-to-date-capabilities.md b/src/2025h2/FLS-up-to-date-capabilities.md index 542c7445..30253967 100644 --- a/src/2025h2/FLS-up-to-date-capabilities.md +++ b/src/2025h2/FLS-up-to-date-capabilities.md @@ -2,7 +2,7 @@ | Metadata | | |:-----------------|----------------------------------------------------------------------------------| -| Point of contact | *@JoelMarcey* | +| Point of contact | @JoelMarcey | | Teams | <!-- #t-spec, #t-lang, #t-opsem --> | | Task owners | <!-- @JoelMarcey --> | | Status | Proposed | @@ -61,4 +61,4 @@ This may be the biggest blocker to making this goal successful. Part of this goa ### What happens if the FLS and Reference combine as one specification document? -That's actually a potential outcome of the `t-spec` work in the future. So this may not be totally theoretical. Hopefully the processes we come up with are not so document specific and they can withstand such a merger. \ No newline at end of file +That's actually a potential outcome of the `t-spec` work in the future. So this may not be totally theoretical. Hopefully the processes we come up with are not so document specific and they can withstand such a merger. From c335c1d97622ce7477fa5a9f9c5e02988b3339b1 Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Fri, 18 Jul 2025 10:07:51 -0700 Subject: [PATCH 8/9] Update FLS-up-to-date-capabilities.md Fix metadata table to pass validation --- src/2025h2/FLS-up-to-date-capabilities.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/2025h2/FLS-up-to-date-capabilities.md b/src/2025h2/FLS-up-to-date-capabilities.md index 30253967..0b99eeb1 100644 --- a/src/2025h2/FLS-up-to-date-capabilities.md +++ b/src/2025h2/FLS-up-to-date-capabilities.md @@ -2,10 +2,10 @@ | Metadata | | |:-----------------|----------------------------------------------------------------------------------| -| Point of contact | @JoelMarcey | -| Teams | <!-- #t-spec, #t-lang, #t-opsem --> | -| Task owners | <!-- @JoelMarcey --> | -| Status | Proposed | +| Point of contact | @JoelMarcey | +| Teams | | +| Task owners | | +| Status | Proposed | | Tracking issue | | | Zulip channel | #t-spec | From 545bf8e1cce997cba58d56a313f4c5f006c1d056 Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Fri, 18 Jul 2025 11:05:20 -0700 Subject: [PATCH 9/9] Update src/2025h2/FLS-up-to-date-capabilities.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rémy Rakic --- src/2025h2/FLS-up-to-date-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/2025h2/FLS-up-to-date-capabilities.md b/src/2025h2/FLS-up-to-date-capabilities.md index 0b99eeb1..a51a9279 100644 --- a/src/2025h2/FLS-up-to-date-capabilities.md +++ b/src/2025h2/FLS-up-to-date-capabilities.md @@ -5,7 +5,7 @@ | Point of contact | @JoelMarcey | | Teams | | | Task owners | | -| Status | Proposed | +| Status | Proposed | | Tracking issue | | | Zulip channel | #t-spec |