Figure out how we can update documentation without doing release

[itamarst]

Replaced by https://clusterhq.atlassian.net/browse/FLOC-561

Currently documentation updates require a new release. This is not ideal.

[itamarst]

How about this:

1. Switch ReadTheDocs to point at release/0.1 branch rather than at the 0.1.0 tag.
2. Branches that should also go into live docs will be merged into the stable release/0.1 branch (in addition to master), via a separate PR.

Implementation will involve documenting this somewhere, and also doing the RTD change.

[wallrj]

That sounds like a good plan. The only problem I can see is that the version selector box will look like

Versions
    latest
    release/0.1

...rather than...

Versions
    latest
    0.1

which is a bit ugly. But no big deal and perhaps there's something we could do to fix that.

[itamarst]

That's... hm. Possibly a problem. It would impact the URL too I guess, and quite possibly the URL will be /en/release%2F0.1/; that we can check. If it's /en/release/0.1/ that's not necessarily a problem, and I guess it's more accurate than /en/0.1.0/ anyway.

[lukemarsden]

That sounds OK, only problem is that existing links (like from http://www.theregister.co.uk/2014/08/13/flocker_software_containerisation/) would break. We'd need to fix that by adding redirects in our nginx proxy I guess?

I would say this is a high priority fix, since https://github.com/ClusterHQ/flocker/issues/564 depends on it, and that is (IMO) impacting on the drop-off rate from people going from our homepage (https://clusterhq.com) and clicking the 'Get Started with Flocker now' link.

[itamarst]

We wouldn't break existing links, just add another default (and maybe hide the old 0.1.0 so it's linkable but doesn't show up by default - "Protected Versions ... won’t show up in your version listings, but will be available once linked to.")

[itamarst]

Our release branch is called release/flocker-0.1. RTD translates this to release-flocker-0.1, which is sort've wierd thing to have in the URL.

[itamarst]

I propose we switch our release branches to be release/0.1 and then RTD will have release-0.1 in the URL, e.g. https://docs.clusterhq.com/en/release-0.1/ which looks fine.

[wallrj]

I noticed that django have somehow configured RTD to use URLs in the following format.

• http://django.readthedocs.org/en/1.5.x/

They have branches named eg stable/1.5.x

• https://github.com/django/django/tree/stable/1.5.x

Could be worth asking them about that.

And their main documentation site doesn't seem to use RTD at all. It's a Django app:

• https://github.com/django/djangoproject.com/blob/master/docs/urls.py

...which allows them more control over their urls.

[itamarst]

Yeah, not clear how. The RTD developer I talked to said he might have the feature I requested done this week (configuragle aliases a-la "latest") so maybe we can just do that.

[itamarst]

Blocked on https://github.com/rtfd/readthedocs.org/issues/893 (or we can rename our release branches if that doesn't happen soon).

[adamtheturtle]

We are moving our development planning to JIRA. This issue is now being tracked at https://clusterhq.atlassian.net/browse/FLOC-561. You are welcome to file additional issues in GitHub if that's easier for you.