2014-01-04 02:08:24 +00:00
|
|
|
Versions
|
|
|
|
|
========
|
|
|
|
|
|
|
|
|
|
Read the Docs supports multiple versions of your repository.
|
|
|
|
|
On the initial import,
|
|
|
|
|
we will create a ``latest`` version.
|
|
|
|
|
This will point at the default branch for your VCS control: ``master``, ``default``, or ``trunk``.
|
|
|
|
|
|
2014-10-19 20:47:51 +00:00
|
|
|
We also create a ``stable`` version,
|
2015-01-26 18:08:58 +00:00
|
|
|
if your project has any tagged releases.
|
2014-10-19 20:47:51 +00:00
|
|
|
``stable`` will be automatically kept up to date to point at your highest version.
|
|
|
|
|
|
2014-01-04 02:11:00 +00:00
|
|
|
How we envision versions working
|
2014-01-04 02:08:24 +00:00
|
|
|
--------------------------------
|
|
|
|
|
|
|
|
|
|
In the normal case,
|
|
|
|
|
the ``latest`` version will always point to the most up to date development code.
|
|
|
|
|
If you develop on a branch that is different than the default for your VCS,
|
|
|
|
|
you should set the **Default Branch** to that branch.
|
|
|
|
|
|
|
|
|
|
You should push a **tag** for each version of your project.
|
|
|
|
|
These tags should be numbered in a way that is consistent with `semantic versioning <http://semver.org/>`_.
|
2014-10-19 20:49:28 +00:00
|
|
|
This will map to your ``stable`` branch by default.
|
2014-01-04 02:08:24 +00:00
|
|
|
|
2015-07-02 12:23:46 +00:00
|
|
|
.. note::
|
|
|
|
|
We in fact are parsing your tag names against the rules given by
|
|
|
|
|
`PEP 440`_. This spec allows "normal" version numbers like ``1.4.2`` as
|
2016-03-11 14:25:21 +00:00
|
|
|
well as pre-releases. An alpha version or a release candidate are examples
|
2015-07-02 12:23:46 +00:00
|
|
|
of pre-releases and they look like this: ``2.0a1``.
|
|
|
|
|
|
|
|
|
|
We only consider non pre-releases for the ``stable`` version of your
|
|
|
|
|
documentation.
|
|
|
|
|
|
2014-01-04 02:13:34 +00:00
|
|
|
If you have documentation changes on a **long-lived branch**,
|
2014-01-04 02:08:24 +00:00
|
|
|
you can build those too.
|
|
|
|
|
This will allow you to see how the new docs will be built in this branch of the code.
|
|
|
|
|
Generally you won't have more than 1 active branch over a long period of time.
|
2014-01-04 02:13:34 +00:00
|
|
|
The main exception here would be **release branches**,
|
2014-01-04 02:08:24 +00:00
|
|
|
which are branches that are maintained over time for a specific release number.
|
|
|
|
|
|
2015-07-02 12:23:46 +00:00
|
|
|
.. _PEP 440: https://www.python.org/dev/peps/pep-0440/
|
|
|
|
|
|
2018-02-09 13:14:15 +00:00
|
|
|
Tags and branches
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
Read the Docs supports two workflows for versioning: based on tags or branches.
|
2018-07-09 22:18:02 +00:00
|
|
|
If you have at least one tag,
|
2018-02-09 13:14:15 +00:00
|
|
|
tags will take preference over branches when selecting the stable version.
|
|
|
|
|
|
2014-01-04 02:08:24 +00:00
|
|
|
Redirects on root URLs
|
|
|
|
|
----------------------
|
|
|
|
|
|
|
|
|
|
When a user hits the root URL for your documentation,
|
2016-04-27 23:14:36 +00:00
|
|
|
for example ``http://pip.readthedocs.io/``,
|
2014-01-17 13:38:30 +00:00
|
|
|
they will be redirected to the **Default version**.
|
2014-01-04 02:08:24 +00:00
|
|
|
This defaults to **latest**,
|
|
|
|
|
but could also point to your latest released version.
|
2018-05-08 04:32:11 +00:00
|
|
|
|
|
|
|
|
Version warning
|
|
|
|
|
---------------
|
|
|
|
|
|
2018-05-15 14:19:03 +00:00
|
|
|
This is a banner that appears on the top of every page of your docs that aren't stable or latest.
|
|
|
|
|
This banner has a text with a link redirecting the users to the latest version of your docs.
|
2018-05-08 04:32:11 +00:00
|
|
|
|
|
|
|
|
This feature is disabled by default on new projects,
|
|
|
|
|
you can enable it in the admin section of your docs (Advanced Settings).
|
