[rustc.git] / src / doc / trpl / release-channels.md

% 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.

As an example, many Rust programmers use [Travis](https://travis-ci.org/) to
test their crates, which is free for open source projects. Travis [supports
Rust directly][travis], and you can use a `.travis.yml` file like this to
test on all channels:

```yaml
language: rust
rust:
  - nightly
  - beta
  - stable

matrix:
  allow_failures:
    - rust: nightly
```

[travis]: http://docs.travis-ci.com/user/languages/rust/

With this configuration, Travis will test all three channels, but if something
breaks on nightly, it won’t fail your build. A similar configuration is
recommended for any CI system, check the documentation of the one you’re
using for more details.
Commit	Line	Data
bd371182 AL	1	% Release Channels
	2
	3	The Rust project uses a concept called ‘release channels’ to manage releases.
	4	It’s important to understand this process to choose which version of Rust
	5	your project should use.
	6
	7	# Overview
	8
	9	There are three channels for Rust releases:
	10
	11	* Nightly
	12	* Beta
	13	* Stable
	14
	15	New nightly releases are created once a day. Every six weeks, the latest
	16	nightly release is promoted to ‘Beta’. At that point, it will only receive
	17	patches to fix serious errors. Six weeks later, the beta is promoted to
	18	‘Stable’, and becomes the next release of `1.x`.
	19
	20	This process happens in parallel. So every six weeks, on the same day,
	21	nightly goes to beta, beta goes to stable. When `1.x` is released, at
	22	the same time, `1.(x + 1)-beta` is released, and the nightly becomes the
	23	first version of `1.(x + 2)-nightly`.
	24
	25	# Choosing a version
	26
	27	Generally speaking, unless you have a specific reason, you should be using the
	28	stable release channel. These releases are intended for a general audience.
	29
	30	However, depending on your interest in Rust, you may choose to use nightly
	31	instead. The basic tradeoff is this: in the nightly channel, you can use
	32	unstable, new Rust features. However, unstable features are subject to change,
	33	and so any new nightly release may break your code. If you use the stable
	34	release, you cannot use experimental features, but the next release of Rust
	35	will not cause significant issues through breaking changes.
	36
	37	# Helping the ecosystem through CI
	38
	39	What about beta? We encourage all Rust users who use the stable release channel
	40	to also test against the beta channel in their continuous integration systems.
	41	This will help alert the team in case there’s an accidental regression.
	42
	43	Additionally, testing against nightly can catch regressions even sooner, and so
	44	if you don’t mind a third build, we’d appreciate testing against all channels.
	45
c1a9b12d SL	46	As an example, many Rust programmers use [Travis](https://travis-ci.org/) to
	47	test their crates, which is free for open source projects. Travis [supports
	48	Rust directly][travis], and you can use a `.travis.yml` file like this to
	49	test on all channels:
	50
	51	```yaml
	52	language: rust
	53	rust:
	54	- nightly
	55	- beta
	56	- stable
	57
	58	matrix:
	59	allow_failures:
	60	- rust: nightly
	61	```
	62
	63	[travis]: http://docs.travis-ci.com/user/languages/rust/
	64
	65	With this configuration, Travis will test all three channels, but if something
	66	breaks on nightly, it won’t fail your build. A similar configuration is
	67	recommended for any CI system, check the documentation of the one you’re
	68	using for more details.