Add a changelog for x.py

- Add a changelog and instructions for updating it
- Use `changelog-seen` in `config.toml` and `VERSION` in bootstrap to determine whether the changelog has been read
- Nag people if they haven't read the x.py changelog
  + Print message twice to make sure it's seen
- Give different error messages depending on whether the version needs to be updated or added

config.toml.example

@@ -9,6 +9,12 @@
 # a custom configuration file can also be specified with `--config` to the build
 # system.
 
+# Keeps track of the last version of `x.py` used.
+# If it does not match the version that is currently running,
+# `x.py` will prompt you to update it and read the changelog.
+# See `src/bootstrap/CHANGELOG.md` for more information.
+changelog-seen = 1
+
 # =============================================================================
 # Global Settings
 # =============================================================================

src/bootstrap/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to bootstrap will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Non-breaking changes since the last major version]
+
+- Add a changelog for x.py [#76626](https://github.com/rust-lang/rust/pull/76626)
+- Optionally, download LLVM from CI on Linux and NixOS
+  + [#76439](https://github.com/rust-lang/rust/pull/76349)
+  + [#76667](https://github.com/rust-lang/rust/pull/76667)
+  + [#76708](https://github.com/rust-lang/rust/pull/76708)
+- Distribute rustc sources as part of `rustc-dev` [#76856](https://github.com/rust-lang/rust/pull/76856)
+- Make the default stage for x.py configurable [#76625](https://github.com/rust-lang/rust/pull/76625)
+- Add a dedicated debug-logging option [#76588](https://github.com/rust-lang/rust/pull/76588)
+- Add sample defaults for x.py [#76628](https://github.com/rust-lang/rust/pull/76628)
+
+## [Version 0] - 2020-09-11
+
+This is the first changelog entry, and it does not attempt to be an exhaustive list of features in x.py.
+Instead, this documents the changes to bootstrap in the past 2 months.
+
+- Improve defaults in `x.py` [#73964](https://github.com/rust-lang/rust/pull/73964)
+  (see [blog post] for details)
+- Set `ninja = true` by default [#74922](https://github.com/rust-lang/rust/pull/74922)
+- Avoid trying to inversely cross-compile for build triple from host triples [#76415](https://github.com/rust-lang/rust/pull/76415)
+- Allow blessing expect-tests in tools [#75975](https://github.com/rust-lang/rust/pull/75975)
+- `x.py check` checks tests/examples/benches [#76258](https://github.com/rust-lang/rust/pull/76258)
+- Fix `rust.use-lld` when linker is not set [#76326](https://github.com/rust-lang/rust/pull/76326)
+- Build tests with LLD if `use-lld = true` was passed [#76378](https://github.com/rust-lang/rust/pull/76378)
+
+[blog post]: https://blog.rust-lang.org/inside-rust/2020/08/30/changes-to-x-py-defaults.html

src/bootstrap/README.md

@@ -313,6 +313,20 @@ are:
   `Config` struct.
 * Adding a sanity check? Take a look at `bootstrap/sanity.rs`.
 
+If you make a major change, please remember to:
+
++ Update `VERSION` in `src/bootstrap/main.rs`.
+* Update `changelog-seen = N` in `config.toml.example`.
+* Add an entry in `src/bootstrap/CHANGELOG.md`.
+
+A 'major change' includes
+
+* A new option or
+* A change in the default options.
+
+Changes that do not affect contributors to the compiler or users
+building rustc from source don't need an update to `VERSION`.
+
 If you have any questions feel free to reach out on the `#t-infra` channel in
 the [Rust Zulip server][rust-zulip] or ask on internals.rust-lang.org. When
 you encounter bugs, please file issues on the rust-lang/rust issue tracker.

src/bootstrap/bin/main.rs

@@ -12,5 +12,40 @@ use bootstrap::{Build, Config};
 fn main() {
     let args = env::args().skip(1).collect::<Vec<_>>();
     let config = Config::parse(&args);
+
+    let changelog_suggestion = check_version(&config);
+    if let Some(suggestion) = &changelog_suggestion {
+        println!("{}", suggestion);
+    }
+
     Build::new(config).build();
+
+    if let Some(suggestion) = changelog_suggestion {
+        println!("{}", suggestion);
+        println!("note: this message was printed twice to make it more likely to be seen");
+    }
+}
+
+fn check_version(config: &Config) -> Option<String> {
+    const VERSION: usize = 1;
+
+    let mut msg = String::new();
+
+    let suggestion = if let Some(seen) = config.changelog_seen {
+        if seen != VERSION {
+            msg.push_str("warning: there have been changes to x.py since you last updated.\n");
+            format!("update `config.toml` to use `changelog-seen = {}` instead", VERSION)
+        } else {
+            return None;
+        }
+    } else {
+        msg.push_str("warning: x.py has made several changes recently you may want to look at\n");
+        format!("add `changelog-seen = {}` to `config.toml`", VERSION)
+    };
+
+    msg.push_str("help: consider looking at the changes in `src/bootstrap/CHANGELOG.md`\n");
+    msg.push_str("note: to silence this warning, ");
+    msg.push_str(&suggestion);
+
+    Some(msg)
 }

src/bootstrap/config.rs

@@ -42,6 +42,7 @@ macro_rules! check_ci_llvm {
 /// `config.toml.example`.
 #[derive(Default)]
 pub struct Config {
+    pub changelog_seen: Option<usize>,
     pub ccache: Option<String>,
     /// Call Build::ninja() instead of this.
     pub ninja_in_file: bool,
@@ -273,6 +274,7 @@ impl Target {
 #[derive(Deserialize, Default)]
 #[serde(deny_unknown_fields, rename_all = "kebab-case")]
 struct TomlConfig {
+    changelog_seen: Option<usize>,
     build: Option<Build>,
     install: Option<Install>,
     llvm: Option<Llvm>,
@@ -283,7 +285,10 @@ struct TomlConfig {
 }
 
 impl Merge for TomlConfig {
-    fn merge(&mut self, TomlConfig { build, install, llvm, rust, dist, target, profile: _ }: Self) {
+    fn merge(
+        &mut self,
+        TomlConfig { build, install, llvm, rust, dist, target, profile: _, changelog_seen: _ }: Self,
+    ) {
         fn do_merge<T: Merge>(x: &mut Option<T>, y: Option<T>) {
             if let Some(new) = y {
                 if let Some(original) = x {
@@ -572,6 +577,8 @@ impl Config {
             toml.merge(included_toml);
         }
 
+        config.changelog_seen = toml.changelog_seen;
+
         let build = toml.build.unwrap_or_default();
 
         // If --target was specified but --host wasn't specified, don't run any host-only tests.