From e07ea499d0fa9f2a5f72655a405b1de96aaee9ad Mon Sep 17 00:00:00 2001 From: Pietro Albini Date: Mon, 16 Sep 2019 11:06:05 +0200 Subject: [PATCH 1/6] ignore vim temporary files when searching for posts --- src/main.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/main.rs b/src/main.rs index eceec2bf3..8db65905e 100644 --- a/src/main.rs +++ b/src/main.rs @@ -121,6 +121,11 @@ impl Blog { // yeah this might blow up, but it won't let filename = path.file_name().unwrap().to_str().unwrap(); + // ignore vim temporary files + if filename.starts_with(".") && filename.ends_with(".swp") { + continue; + } + // we need to get the metadata out of the url let mut split = filename.splitn(4, "-"); From d4f8e77ef5d7d8062ab25974afb6c93885d65c2f Mon Sep 17 00:00:00 2001 From: Pietro Albini Date: Mon, 16 Sep 2019 12:23:18 +0200 Subject: [PATCH 2/6] add post about the upcoming docs.rs changes --- posts/2019-09-18-upcoming-docsrs-changes.md | 85 +++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 posts/2019-09-18-upcoming-docsrs-changes.md diff --git a/posts/2019-09-18-upcoming-docsrs-changes.md b/posts/2019-09-18-upcoming-docsrs-changes.md new file mode 100644 index 000000000..648ed42b6 --- /dev/null +++ b/posts/2019-09-18-upcoming-docsrs-changes.md @@ -0,0 +1,85 @@ +--- +layout: post +title: "Upcoming docs.rs changes" +author: The Rust Infrastructure Team +--- + +On September 42nd breaking changes will be deployed to the [docs.rs] build +environment. [docs.rs] is a free service building and hosting documentation for +all the crates published on [crates.io]. It's [open source][docsrs-source] and +maintained by the [Rustdoc team][rustdoc-team]. + +## What will change + +Builds will be executed inside the [rustops/crates-build-env] Docker image. +That image contains a lot of system dependencies installed to ensure we can +build as many crates as possible. It's already used by [Crater], and we added +all the dependencies previously installed in the legacy build environment. + +To ensure we can continue operating the service in the future and to increase +its reliability we also improved the sandbox builds are executed into, adding +new limits: + +* Each platform will now have **15 minutes** to build its dependencies and + documentation. +* **3 GB of RAM** will be available for the build. +* Network access will be completly **disabled**. +* Only the `target/` directory will be writable, and it will be purged after + each build. + +Finally, docs.rs will now use the latest nightly available when building +crates. + +## How to prepare for the changes + +To test if your crate builds inside the new environment you can download the +Docker image locally and execute a shell inside it: + +``` +docker pull rustops/crates-build-env +docker run --rm -it rustops/crates-build-env bash +``` + +Once you're in a shell you can install [rustup] (it's not installed in the +image), install Rust nightly, clone your crate's repository and then build the +documentation: + +``` +cargo doc --no-deps +``` + +If a dependency is missing please [open an issue][crates-build-env-issue] on +the Docker image's repository. + +If your crate fails to build because it took more than 15 minutes to generate +its docs or it uses more than 3 GB of RAM please [open an issue][docsrs-issue] +and we will increase the limits for your crate (when it's reasonable). We will +**not** enable network access for your crate though: you'll need to change your +crate not to require any external resource at build time. + +## Acknowledgements + +The new build environment is based on [Rustwide], the library powering +[Crater]. It was extracted from the Crater codebase, and created both by the +[Crater contributors] and the [Rustwide contributors]. + +The implementation work on the docs.rs side was done by [Pietro Albini][pietro] +and [Onur Aslan][onur], with [QuietMisdreavus][misdreavus] and [Mark +Rousskov][mark] reviewing the changes. + +[docs.rs]: https://docs.rs +[crates.io]: https://crates.io +[docsrs-source]: https://github.com/rust-lang/docs.rs +[rustdoc-team]: https://www.rust-lang.org/governance/teams/dev-tools#rustdoc +[rustops/crates-build-env]: https://hub.docker.com/r/rustops/crates-build-env +[Crater]: https://github.com/rust-lang/crater +[rustup]: https://rustup.rs +[crates-build-env-issue]: https://github.com/rust-lang/crates-build-env/issues +[docsrs-issue]: https://github.com/rust-lang/crates-build-env/issues +[rustwide]: https://github.com/rust-lang/rustwide +[Crater contributors]: https://github.com/rust-lang/crater/graphs/contributors +[Rustwide contributors]: https://github.com/rust-lang/rustwide/graphs/contributors +[pietro]: https://github.com/pietroalbini +[onur]: https://github.com/onur +[mark]: https://github.com/Mark-Simulacrum +[misdreavus]: https://github.com/QuietMisdreavus From 5c6a99dcd631d2806bbd11abcfc82b8e868cd1cc Mon Sep 17 00:00:00 2001 From: Pietro Albini Date: Mon, 16 Sep 2019 15:42:59 +0200 Subject: [PATCH 3/6] address some of the review comments --- posts/2019-09-18-upcoming-docsrs-changes.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/posts/2019-09-18-upcoming-docsrs-changes.md b/posts/2019-09-18-upcoming-docsrs-changes.md index 648ed42b6..5ec38bbfa 100644 --- a/posts/2019-09-18-upcoming-docsrs-changes.md +++ b/posts/2019-09-18-upcoming-docsrs-changes.md @@ -17,18 +17,19 @@ build as many crates as possible. It's already used by [Crater], and we added all the dependencies previously installed in the legacy build environment. To ensure we can continue operating the service in the future and to increase -its reliability we also improved the sandbox builds are executed into, adding +its reliability we also improved the sandbox builds are executed in, adding new limits: * Each platform will now have **15 minutes** to build its dependencies and documentation. * **3 GB of RAM** will be available for the build. -* Network access will be completly **disabled**. +* Network access will be **disabled** (crates.io dependencies will still be + fetched). * Only the `target/` directory will be writable, and it will be purged after each build. Finally, docs.rs will now use the latest nightly available when building -crates. +crates, instead of using a manually updated pinned version of nightly. ## How to prepare for the changes @@ -48,14 +49,14 @@ documentation: cargo doc --no-deps ``` -If a dependency is missing please [open an issue][crates-build-env-issue] on -the Docker image's repository. +If a dependency is missing, please [open an issue][crates-build-env-issue] on +the Docker image's [repository][rustops/crates-build-env]. If your crate fails to build because it took more than 15 minutes to generate its docs or it uses more than 3 GB of RAM please [open an issue][docsrs-issue] -and we will increase the limits for your crate (when it's reasonable). We will -**not** enable network access for your crate though: you'll need to change your -crate not to require any external resource at build time. +and we will consider reasonable limit increases for your crate. We will **not** +enable network access for your crate though: you'll need to change your crate +not to require any external resource at build time. ## Acknowledgements From 3dec78f0b65432345f93ab1729ce51962282b982 Mon Sep 17 00:00:00 2001 From: Pietro Albini Date: Tue, 17 Sep 2019 19:25:45 +0200 Subject: [PATCH 4/6] update docs.rs breaking change date --- posts/2019-09-18-upcoming-docsrs-changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/posts/2019-09-18-upcoming-docsrs-changes.md b/posts/2019-09-18-upcoming-docsrs-changes.md index 5ec38bbfa..73b91c3b3 100644 --- a/posts/2019-09-18-upcoming-docsrs-changes.md +++ b/posts/2019-09-18-upcoming-docsrs-changes.md @@ -4,7 +4,7 @@ title: "Upcoming docs.rs changes" author: The Rust Infrastructure Team --- -On September 42nd breaking changes will be deployed to the [docs.rs] build +On September 30nd breaking changes will be deployed to the [docs.rs] build environment. [docs.rs] is a free service building and hosting documentation for all the crates published on [crates.io]. It's [open source][docsrs-source] and maintained by the [Rustdoc team][rustdoc-team]. From eedcf8d95bfbe6ad04fd0e534b7e42f3f340c8a8 Mon Sep 17 00:00:00 2001 From: Pietro Albini Date: Tue, 17 Sep 2019 19:48:23 +0200 Subject: [PATCH 5/6] I'm bad at multitasking --- posts/2019-09-18-upcoming-docsrs-changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/posts/2019-09-18-upcoming-docsrs-changes.md b/posts/2019-09-18-upcoming-docsrs-changes.md index 73b91c3b3..7dc5d4dc2 100644 --- a/posts/2019-09-18-upcoming-docsrs-changes.md +++ b/posts/2019-09-18-upcoming-docsrs-changes.md @@ -4,7 +4,7 @@ title: "Upcoming docs.rs changes" author: The Rust Infrastructure Team --- -On September 30nd breaking changes will be deployed to the [docs.rs] build +On September 30th breaking changes will be deployed to the [docs.rs] build environment. [docs.rs] is a free service building and hosting documentation for all the crates published on [crates.io]. It's [open source][docsrs-source] and maintained by the [Rustdoc team][rustdoc-team]. From 6ff3fb9513df2d9487095b7dff0b9cf8fb945f07 Mon Sep 17 00:00:00 2001 From: Pietro Albini Date: Wed, 18 Sep 2019 09:45:12 +0200 Subject: [PATCH 6/6] last fixes to the post --- posts/2019-09-18-upcoming-docsrs-changes.md | 32 ++++++++++++++------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/posts/2019-09-18-upcoming-docsrs-changes.md b/posts/2019-09-18-upcoming-docsrs-changes.md index 7dc5d4dc2..6b30f4a17 100644 --- a/posts/2019-09-18-upcoming-docsrs-changes.md +++ b/posts/2019-09-18-upcoming-docsrs-changes.md @@ -6,8 +6,9 @@ author: The Rust Infrastructure Team On September 30th breaking changes will be deployed to the [docs.rs] build environment. [docs.rs] is a free service building and hosting documentation for -all the crates published on [crates.io]. It's [open source][docsrs-source] and -maintained by the [Rustdoc team][rustdoc-team]. +all the crates published on [crates.io]. It's [open source][docsrs-source], +maintained by the [Rustdoc team][rustdoc-team] and operated by the +[Infrastructure team][infra-team]. ## What will change @@ -17,7 +18,7 @@ build as many crates as possible. It's already used by [Crater], and we added all the dependencies previously installed in the legacy build environment. To ensure we can continue operating the service in the future and to increase -its reliability we also improved the sandbox builds are executed in, adding +its reliability we also improved the sandbox the builds are executed in, adding new limits: * Each platform will now have **15 minutes** to build its dependencies and @@ -38,19 +39,24 @@ Docker image locally and execute a shell inside it: ``` docker pull rustops/crates-build-env -docker run --rm -it rustops/crates-build-env bash +docker run --rm --memory 3221225472 -it rustops/crates-build-env bash ``` -Once you're in a shell you can install [rustup] (it's not installed in the -image), install Rust nightly, clone your crate's repository and then build the -documentation: +Once you're in a shell you can install [rustup] (it's not installed by default +in the image), install Rust nightly, clone your crate's repository and then +build the documentation: ``` -cargo doc --no-deps +time cargo doc --no-deps ``` -If a dependency is missing, please [open an issue][crates-build-env-issue] on -the Docker image's [repository][rustops/crates-build-env]. +To aid your testing these commands will limit the available RAM to 3 GB and +show the total execution time of `cargo doc`, but network access will not be +blocked as you'll need to fetch dependencies. + +If your project needs a system dependency missing in the build environment, +please [open an issue][crates-build-env-issue] on the Docker image's +[repository][rustops/crates-build-env] and we'll consider adding it. If your crate fails to build because it took more than 15 minutes to generate its docs or it uses more than 3 GB of RAM please [open an issue][docsrs-issue] @@ -58,6 +64,9 @@ and we will consider reasonable limit increases for your crate. We will **not** enable network access for your crate though: you'll need to change your crate not to require any external resource at build time. +We recommend using [Cargo features] to remove the parts of the code causing +build failures, enabling those features with [docs.rs metadata]. + ## Acknowledgements The new build environment is based on [Rustwide], the library powering @@ -72,11 +81,14 @@ Rousskov][mark] reviewing the changes. [crates.io]: https://crates.io [docsrs-source]: https://github.com/rust-lang/docs.rs [rustdoc-team]: https://www.rust-lang.org/governance/teams/dev-tools#rustdoc +[infra-team]: https://www.rust-lang.org/governance/teams/operations#infra [rustops/crates-build-env]: https://hub.docker.com/r/rustops/crates-build-env [Crater]: https://github.com/rust-lang/crater [rustup]: https://rustup.rs [crates-build-env-issue]: https://github.com/rust-lang/crates-build-env/issues [docsrs-issue]: https://github.com/rust-lang/crates-build-env/issues +[Cargo features]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section +[docs.rs metadata]: https://docs.rs/about [rustwide]: https://github.com/rust-lang/rustwide [Crater contributors]: https://github.com/rust-lang/crater/graphs/contributors [Rustwide contributors]: https://github.com/rust-lang/rustwide/graphs/contributors