feat(cli): notify when a new stable Rust release is available

Author: FranciscoTGouveia

doc/user-guide/src/environment-variables.md

@@ -47,6 +47,10 @@
 - `RUSTUP_NO_BACKTRACE`. Disables backtraces on non-panic errors even when
   `RUST_BACKTRACE` is set.
 
+- `RUSTUP_RELEASE_HINT` (default: `1`). When set to `1`, shows a hint when a
+  new stable Rust release is (likely) available. Set this value to `0` to
+  suppress the hint.
+
 - `RUSTUP_PERMIT_COPY_RENAME` *unstable*. When set, allows rustup to fall-back
   to copying files if attempts to `rename` result in cross-device link
   errors. These errors occur on OverlayFS, which is used by [Docker][dc]. This

src/cli/common.rs

@@ -4,11 +4,14 @@ use std::fmt::Display;
 use std::fs;
 use std::io::{BufRead, Write};
 use std::path::Path;
+use std::str::FromStr;
 use std::sync::LazyLock;
+use std::time::{SystemTime, UNIX_EPOCH};
 use std::{cmp, env};
 
 use anstyle::Style;
 use anyhow::{Context, Result, anyhow};
+use chrono::{DateTime, NaiveDate};
 use clap_cargo::style::{CONTEXT, ERROR, UPDATE_ADDED, UPDATE_UNCHANGED, UPDATE_UPGRADED};
 use futures_util::future::join_all;
 use git_testament::{git_testament, render_testament};
@@ -17,15 +20,18 @@ use tracing_subscriber::{EnvFilter, Registry, reload::Handle};
 
 use crate::{
     config::Cfg,
-    dist::{DistOptions, TargetTuple, ToolchainDesc},
+    dist::{DistOptions, PartialToolchainDesc, TargetTuple, ToolchainDesc},
     errors::RustupError,
     install::{InstallMethod, UpdateStatus},
     process::Process,
-    toolchain::{LocalToolchainName, Toolchain, ToolchainName},
+    toolchain::{DistributableToolchain, LocalToolchainName, Toolchain, ToolchainName},
     utils::{self, ExitCode},
 };
 
 pub(crate) const WARN_COMPLETE_PROFILE: &str = "downloading with complete profile isn't recommended unless you are a developer of the rust language";
+const RELEASE_CYCLE_DAYS: i64 = 42;
+const NOTIFY_INTERVAL_SECS: u64 = 24 * 60 * 60;
+const FALLBACK_RELEASE_DATE: &str = "2026-04-17";
 
 pub(crate) fn confirm(question: &str, default: bool, process: &Process) -> Result<bool> {
     write!(process.stdout().lock(), "{question} ")?;
@@ -569,3 +575,61 @@ pub(super) fn update_console_filter(
             .expect("error reloading `EnvFilter` for console_logger");
     }
 }
+
+/// Notifies a user with a hint whenever a new Rust release is available.
+/// This is only shown at max once per day and only if not in proxy mode.
+pub(crate) fn notify_release(cfg: &Cfg<'_>) -> Result<()> {
+    if cfg.process.var("RUSTUP_RELEASE_HINT").ok().as_deref() == Some("0") {
+        return Ok(());
+    }
+
+    let time_now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs();
+
+    // Limit notifications to at most once per day.
+    // This is checked before loading the manifest to avoid unnecessary disk I/O.
+    let last_notified = cfg
+        .settings_file
+        .with(|s| Ok(s.last_release_notified_secs.unwrap_or(0)))?;
+    if time_now.saturating_sub(last_notified) < NOTIFY_INTERVAL_SECS {
+        return Ok(());
+    }
+
+    let default_host = cfg.default_host_tuple()?;
+    let stable_desc = PartialToolchainDesc::from_str("stable")?.resolve(&default_host)?;
+    let distributable = DistributableToolchain::new(cfg, stable_desc)
+        .map_err(|e| anyhow!("stable toolchain unavailable: {e}"))?;
+    let release_date_str = match distributable.get_manifestation() {
+        Ok(manifestation) => match manifestation.load_manifest() {
+            Ok(Some(manifest)) => manifest.date,
+            Ok(None) | Err(_) => FALLBACK_RELEASE_DATE.to_owned(),
+        },
+        Err(_) => FALLBACK_RELEASE_DATE.to_owned(),
+    };
+
+    let today = DateTime::from_timestamp(time_now as i64, 0)
+        .unwrap_or_default()
+        .date_naive();
+
+    let release_date = NaiveDate::parse_from_str(&release_date_str, "%Y-%m-%d")
+        .map_err(|e| anyhow!("could not parse release date '{}': {e}", release_date_str))?;
+
+    // Skip the hint if fewer than 6 weeks have passed since the last known release.
+    if (today - release_date).num_days() < RELEASE_CYCLE_DAYS {
+        return Ok(());
+    }
+
+    cfg.settings_file.with_mut(|s| {
+        s.last_release_notified_secs = Some(time_now);
+        Ok(())
+    })?;
+
+    writeln!(
+        cfg.process.stderr().lock(),
+        "hint: a new stable Rust release is available. Run `rustup update stable` to install it."
+    )?;
+
+    Ok(())
+}

src/cli/rustup_mode.rs

@@ -707,6 +707,12 @@ pub async fn main(
 
     let should_warn = subcmd.should_warn_empty_setup();
 
+    let should_notify = !matches.quiet
+        && !matches!(
+            subcmd,
+            RustupSubcmd::Update { .. } | RustupSubcmd::Install { .. }
+        );
+
     let exit_code = match subcmd {
         RustupSubcmd::DumpTestament => common::dump_testament(process),
         RustupSubcmd::Install { opts } => update(cfg, opts, true).await,
@@ -840,6 +846,10 @@ pub async fn main(
         warn!("no toolchain installed and no default toolchain set\n{DEFAULT_STABLE_HINT}");
     }
 
+    if should_notify {
+        let _ = common::notify_release(cfg);
+    }
+
     Ok(exit_code)
 }
 

src/settings.rs

@@ -96,6 +96,8 @@ pub struct Settings {
     pub auto_self_update: Option<SelfUpdateMode>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub auto_install: Option<AutoInstallMode>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub last_release_notified_secs: Option<u64>,
 }
 
 impl Settings {

tests/suite/cli_rustup.rs

@@ -880,7 +880,10 @@ installed targets:
   [HOST_TUPLE]
 
 "#]])
-        .with_stderr(snapbox::str![[""]])
+        .with_stderr(snapbox::str![[r#"
+hint: a new stable Rust release is available. Run `rustup update stable` to install it.
+
+"#]])
         .is_ok();
 }
 

tests/suite/cli_self_upd.rs

@@ -434,6 +434,7 @@ async fn update_exact() {
         .with_stderr(snapbox::str![[r#"
 info: checking for self-update (current version: [CURRENT_VERSION])
 info: downloading self-update (new version: [TEST_VERSION])
+hint: a new stable Rust release is available. Run `rustup update stable` to install it.
 
 "#]])
         .is_ok();
@@ -462,6 +463,7 @@ async fn update_precise() {
 info: checking for self-update (current version: [CURRENT_VERSION])
 info: `RUSTUP_VERSION` has been set to `[TEST_VERSION]`
 info: downloading self-update (new version: [TEST_VERSION])
+hint: a new stable Rust release is available. Run `rustup update stable` to install it.
 
 "#]]);
 }
@@ -650,6 +652,7 @@ async fn update_no_change() {
 "#]])
         .with_stderr(snapbox::str![[r#"
 info: checking for self-update (current version: [CURRENT_VERSION])
+hint: a new stable Rust release is available. Run `rustup update stable` to install it.
 
 "#]])
         .is_ok();
@@ -1112,6 +1115,7 @@ async fn update_does_not_overwrite_rustfmt() {
         .with_stderr(snapbox::str![[r#"
 info: checking for self-update (current version: [CURRENT_VERSION])
 warn: tool `rustfmt` is already installed, remove it from `[..]`, then run `rustup update` to have rustup manage this tool.
+hint: a new stable Rust release is available. Run `rustup update stable` to install it.
 
 "#]])
         .is_ok();