TRPL: release channels

2 files changed, 46 insertions, 0 deletions

diff --git a/src/doc/trpl/SUMMARY.md b/src/doc/trpl/SUMMARY.md
index de7ded76280..fef61dcc702 100644
--- a/src/doc/trpl/SUMMARY.md
+++ b/src/doc/trpl/SUMMARY.md
@@ -15,6 +15,7 @@
     * [Concurrency](concurrency.md)
     * [Error Handling](error-handling.md)
     * [FFI](ffi.md)
+    * [Release Channels](release-channels.md)
 * [Syntax and Semantics](syntax-and-semantics.md)
     * [Variable Bindings](variable-bindings.md)
     * [Functions](functions.md)
diff --git a/src/doc/trpl/release-channels.md b/src/doc/trpl/release-channels.md
new file mode 100644
index 00000000000..03e65539a20
--- /dev/null
+++ b/src/doc/trpl/release-channels.md
@@ -0,0 +1,45 @@
+% Release Channels
+
+The Rust project uses a concept called ‘release channels’ to manage releases.
+It’s important to understand this process to choose which version of Rust
+your project should use.
+
+# Overview
+
+There are three channels for Rust releases:
+
+* Nightly
+* Beta
+* Stable
+
+New nightly releases are created once a day. Every six weeks, the latest
+nightly release is promoted to ‘Beta’. At that point, it will only receive
+patches to fix serious errors. Six weeks later, the beta is promoted to
+‘Stable’, and becomes the next release of `1.x`.
+
+This process happens in parallel. So every six weeks, on the same day,
+nightly goes to beta, beta goes to stable. When `1.x` is released, at
+the same time, `1.(x + 1)-beta` is released, and the nightly becomes the
+first version of `1.(x + 2)-nightly`.
+
+# Choosing a version
+
+Generally speaking, unless you have a specific reason, you should be using the
+stable release channel. These releases are intended for a general audience.
+
+However, depending on your interest in Rust, you may choose to use nightly
+instead. The basic tradeoff is this: in the nightly channel, you can use
+unstable, new Rust features. However, unstable features are subject to change,
+and so any new nightly release may break your code. If you use the stable
+release, you cannot use experimental features, but the next release of Rust
+will not cause significant issues through breaking changes.
+
+# Helping the ecosystem through CI
+
+What about beta? We encourage all Rust users who use the stable release channel
+to also test against the beta channel in their continuous integration systems.
+This will help alert the team in case there’s an accidental regression.
+
+Additionally, testing against nightly can catch regressions even sooner, and so
+if you don’t mind a third build, we’d appreciate testing against all channels.
+