Readthedocs.org: "stable" appearing to track future release branches

[andrewgodwin]

Details

• Project URL: http://channels.readthedocs.io
• Build URL (if applicable): http://channels.readthedocs.io/en/stable/
• Read the Docs username (if applicable): andrewgodwin

Expected Result

I expect the "stable" build version to only follow tags, not new branches, as described in http://docs.readthedocs.io/en/latest/versions.html

Actual Result

The "stable" build says it is following origin/2.0, which looks like a reference to a remote Git branch rather than the project's most recent tag, 1.1.8, which means the "stable" docs have ended up being the in-development version docs.

The "wipe" command does not appear to fix this, and I would like to avoid deleting and remaking the project just to see if it's a bad tag being stored somewhere.

[RichardLitt]

> git ls-remote --tags [email protected]:django/channels.git

Shows that the most recent tag is indeed 1.1.8. Looks like a bug to me.

[willingc]

@andrewgodwin I just took a couple of screenshots of our JupyterHub configuration settings in RTD:

This first screenshot shows the far right settings menu with Advanced Settings selected.

This screenshot shows the Versions page when selected from the far right settings menu (This is different than the top level versions menu). Double check that the versions desired match what you wish to build and see what SHA the stable version when enabled is picking up.

If these settings are not correct, wipe will have no effect.

Unfortunately, I can't see your settings. Let me know if you have further questions. Traveling the rest of the day but will be around tomorrow/Friday.

[andrewgodwin]

There's not even a SHA in my stable build, there is origin/2 again - here's screenshots of the same pages from the Channels project:

[agjohnson]

I'll have to confirm this tomorrow, but my initial thoughts here are that we are in fact determining that the 2.0 branch is to take precedence over 1.x series. If the 2.0 branch were to be named something along the lines of 2.0b1, this might not surface. This isn't a good solution for your case, @andrewgodwin.

Agreed that tags should probably take precedence over a branch name. I'm not fully certain of the best UX here though -- making versioning work for everyone is hard. Perhaps we need a way to turn off the handy wavy magic we do here to select a new version.

I'll poke this tomorrow when I'm fresher.

[andrewgodwin]

Right, I wasn't clear if stable was just tags or branches - I thought it was just tags, since we use branches for all sorts of things and haven't had this before (though I guess they didn't look like a version number).

I don't mind too much what it is as long as it's well defined, but given I have a lot of links on the internet pointing to /stable/, some sort of alias/redirect-to-latest feature would be nice if it's determined this is working as intended, because right now people think my docs are broken.

[willingc]

@agjohnson @andrewgodwin FWIW, one difference that we do with JupyterHub and friends is use a configuration file for RTD (readthedocs.yml) in the base of our project repo.

• conda (environment.yml): https://github.com/jupyterhub/jupyterhub/blob/master/readthedocs.yml
• pip (requirements.txt): https://github.com/jupyter/nbgrader/blob/master/readthedocs.yaml

In setting up a test build on RTD (https://readthedocs.org/projects/test-channels/) using my fork as the source (https://github.com/willingc/channels) to see if the above configuration would change Andrew's build experience for stable, I discovered that trying to rebuild stable from the drop down selection on the main page or the build page results in a page with an API deprecation warning:

Endpoint is deprecated

UI

I think this is likely part of the problem. I, too, with the test build did not have a SHA for the stable version in the Versions page above.

[humitos]

I discovered that trying to rebuild stable from the drop down selection on the main page or the build page results in a page with an API deprecation warning

Ups... Sorry. That's a bug that's already fixed in this PR at https://github.com/rtfd/readthedocs.org/pull/3260

Seems it's not deployed yet.

It _shouldn't_ be related with andrew's issue regarding the stable version.

[agjohnson]

@andrewgodwin if this goes on for longer without resolution lets just get a temporary redirect in at the web server level or something.

I'll see if one of us can't get to this tomorrow, i ended up swamped with work today.

[andrewgodwin]

Cool, thanks for your help on this!

[humitos]

I did a quick test on my local instance and it was pretty easy to reproduce andrew's report. I created a git repo with master and 1.0 branches and one tag 0.9. RTD mark 1.0 as stable.

The code that decide the stable version is: https://github.com/rtfd/readthedocs.org/blob/7cbda6a9b318dc182cd304332a3045a1c53a4aef/readthedocs/projects/version_handling.py#L174-L189

where version_list is Project.versions.all() (this query includes branches and tags) and then in the determine_stable_version branch or tag doesn't matter, they are treated as the same.

I wrote an horrible hack that make tags take preference over branches and I tested with the channels repo and 1.1.8 was what I got as stable, but I think we need to define in a clear way how we want this to work. I mean, how is the logic to decide what should be the sable verision.

Once we have that defined and clear, I could try to write the chunk of code and test needed for this. It will probably involve touching other parts of the codebase also.

What are you thoughts on the logic to decide the stable?

[willingc]

Nice work @humitos. I'm cool with your logic. As a user, I would love to be able to provide a SHA commit for what I would like to have as stable and just have the default stable come in to play if I don't provide the SHA.

[andrewgodwin]

Ah, I did wonder if it was something like that. For reference, the "versions" doc at http://docs.readthedocs.io/en/latest/versions.html describes stable as We also create a stable version, if your project has any tagged releases, so I had thought it was already preferring tags.

[humitos]

As a user, I would love to be able to provide a SHA commit for what I would like to have as stable and just have the default stable come in to play if I don't provide the SHA.

That could be a good feature. But, suposing that the stable version would be working properly, I think it shouldn't be necessary and it could make more confusion maybe. Anyway, I will create a new issue to discuss about this feature and not mix with this report.

That's why I wanted to more feedback on how the stable version should be determined to think in some cases that "take preference of tags over branches" won't work for a project/user.

[humitos]

We also create a stable version, if your project has any tagged releases

Well, this sentence is very confusing for me because of that comma. My English knowledge doesn't help here.

I suppose that it has the same meaning than "If your project has any tagged releases, we also create a stable version". So, I understand that the stable version is only created when your project doesn't have any tagged release, that's not the case of channels and the stable is created anyway, right?

If I'm right, we should re-write that chunk of the documentation also.

[andrewgodwin]

Channels does indeed have tagged releases, quite a few of them - the most recent being 1.1.8

[humitos]

I'm taking a look at this issue. I already proposed a PR but I have a doubt on this.

With the patch applied in my local instance and latest (pointing to master), stable (pointing to 07053beb), 2.0 (pointing to the branch 2.0) and 1.1.8 (pointing to 07053beb) as active versions, when I open

http://localhost:8000/docs/channels/en/1.1.8/

I see this message:

but when I open stable I don't.

My question is, how this should work?

1. Is it OK to point the user to 2.0?
2. should it detect that 1.1.8 is the same as stable and do not suggest anything?
3. this should keep like it is and the RTD user should inactive 1.1.8?
4. only tags should be considered for this?
5. tags should take preference over branches for this?

What do you think?

[humitos]

Meh, wrong button clicked :/

[andrewgodwin]

In my case, because 2.0 is a development branch and not a tag, I don't want it shown as a new version. However, if you want to decide that branches also imply versions, then I'd appreciate this being documented and a workaround suggested (like "name development branches 2.x")

[willingc]

I completely agree with @andrewgodwin re: versions and what is stable.

[agjohnson]

This is slated for next release, most likely going out this week.

[andrewgodwin]

Great! Thanks all.

[ericholscher]

Believe this should be deployed -- let me know if it's resolved.

[andrewgodwin]

I can't seem to shift the stable release off of origin/2.0 yet - I've tried pushing a new commit to master, tagging a new commit on master as 1.1.8.1, wiping and triggering a rebuild. Any recommendations on what the best way to jump it back to the tags might be?

[humitos]

Mmm... weird. It should just work. Sorry about that.

I just updated my master branch, ran it locally and "triggered the build" for version 0.7 of channels from the "Versions" tab. The tag 1.1.8.1 was created. Besides, stable was updated to point to the same commit than 1.1.8.1...

I will try to take a look at this tomorrow.

[ericholscher]

Believe this is because the machine tag was removed when you edited the
stable version. This will stop us from updating it in the future. I have
re-added it for now (and we should document this, as well)

On Wed, Nov 29, 2017 at 6:40 PM Manuel Kaufmann [e-mail]
wrote:

Mmm... weird. It should just work. Sorry about that.

I just updated my master branch, ran it locally and "triggered the build"
for version 0.7 of channels from the "Versions" tab. The tag 1.1.8.1 was
created. Besides, stable was updated to point to the same commit than
1.1.8.1...

[image: captura de pantalla_2017-11-29_21-33-07]
https://user-images.githubusercontent.com/244656/33410285-85dbfa56-d54d-11e7-9285-53a5c5584448.png

—
You are receiving this because you modified the open/close state.
Reply to this email directly, view it on GitHub
https://github.com/rtfd/readthedocs.org/issues/3268#issuecomment-348065022,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AABjppgE73xL3rWaezEYxiOImp5tsypFks5s7hWDgaJpZM4Qeh5Y
.

>

Eric Holscher
Co-founder, Read the Docs & Write the Docs
Director, Python Software Foundation
http://ericholscher.com

[andrewgodwin]

When you say "machine tag", is that the same as the "tags" field I see in the Edit screen, or something else? And would another push to master or another tag trigger stable to re-pin to that?

[ericholscher]

This is an internal thing that we track, for versions we have created: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/projects/models.py#L710

[ericholscher]

Any build should fix it now though.

[ericholscher]

Stable looks :+1: here: https://readthedocs.org/projects/channels/versions/ (stable ebe7100c)

[andrewgodwin]

Ah, perfect, all fixed. Thanks!

[humitos]

Ah, perfect, all fixed. Thanks!

Happy to read this :)

Believe this is because the machine tag was removed when you edited the stable version. This will stop us from updating it in the future. I have re-added it for now (and we should document this, as well)

@ericholscher I don't understand this. "you edited the stable version", who are you refering to here? Me, Andrew?

Anyway, I don't understand how the machine field could be changed. I'm more confused, ha!

[ericholscher]

@humitos when a person disables the version, we set machine = False: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/projects/views/private.py#L179 -- then we check for machine=True when updating stable. But we should really just be respecting the active flag, because there is no way for the user to turn machine back on :)

[ericholscher]

I'll do a PR for that one.

[humitos]

Got it! Thanks for the exaplanation.

[akien-mga]

Is there no way to configure the stable branch manually without having to rely on the magic performed here?

I just noticed that our stable version changed for Godot Engine (http://docs.godotengine.org/en/stable/index.html ) when I pushed a 3.0 branch on our git repository: https://github.com/godotengine/godot-demo-projects

But our stable version is currently the 2.0 branch, the 3.0 one is for the soon-to-be-released version. We needed to have the http://docs.godotengine.org/en/3.0/ namespace available for in-engine documentation references.

I'd prefer to have more control on what I want to show to users as the current "stable" version, instead of having it change automagically.

(Note that I'll gladly turn this comment into a proper feature request if that's considered useful).

[stsewd]

@akien-mga the stable release is chosen following the pep-440 you can use a pre-release branch https://www.python.org/dev/peps/pep-0440/#pre-releases

[akien-mga]

the stable release is chosen following the pep-440 you can use a pre-release branch https://www.python.org/dev/peps/pep-0440/#pre-releases

That doesn't work for my use case, as I want to use the http://docs.godotengine.org/en/3.0/ namespace now even though it's not released yet. Our documentation for releases is not static, it evolves daily based on PRs from contributors (so I want the 3.0 branch to follow the master/latest branch until the real release and incompatible changes in 3.x happen).

[akien-mga]

I guess I can just disable the stable version and try to work around the hundreds of broken links with a redirect from /en/stable to /en/2.1 - and update that redirect when I want to change the stable version.

Edit: Doesn't work as I need to use an Exact Redirect so it will work only for http://docs.godotengine.org/en/stable, not for http://docs.godotengine.org/en/stable/index.html.
Also it shows automatically an infobox that this is not the latest version and that users should use the 3.0 docs instead...

Don't misinterpret me, that feature is great for libraries, but for our use case we really need more control...

[humitos]

Is there no way to configure the stable branch manually without having to rely on the magic performed here?

Unfortunately, no.

But our stable version is currently the 2.0 branch, the 3.0 one is for the soon-to-be-released version. We needed to have the http://docs.godotengine.org/en/3.0 namespace available for in-engine documentation references.

If you want to keep 2.0 as the stable while having a 3.0 branch, you can create a tag for 2.0 and that will be considered the stable. That way, RTD will take preferences for tags over branches to decide which one is the stable.

(in fact, that's exactly what this issue was about and was fixed)

[akien-mga]

If you want to keep 2.0 as the stable while having a 3.0 branch, you can create a tag for 2.0 and that will be considered the stable. That way, RTD will take preferences for tags over changes to decide which one is the stable.

Thanks, I've tried that but it doesn't seem to work: https://github.com/godotengine/godot-docs/releases/tag/2.1 (btw our stable is 2.1, I made a typo above).

It looks like the tag became a version 2.1_a since the 2.1 branch existed already: https://readthedocs.org/projects/godot/versions/

Edit: I'm deleting our 3.0 branch for now as too many users are being confused by getting the wrong docs on stable.

[akien-mga]

I've tried deleting the 3.0 branch, disabling it, pushing a new commit to the 2.1 branch, but nothing goes, stable still tracks a non-existing origin/3.0... https://readthedocs.org/projects/godot/versions/

[humitos]

Mmm... "This seems like a bug in the new feature". @akien-mga would you mind opening a new issue explaining this and what are the steps to reproduce it? Like, what branches do the repository needs and in which order should be created and the attemp to workaround with the tag, etc... so we can test it locally and see how it behaves?

[akien-mga]

Will do, but I'll have to make a test RTD project for it as I would prefer to avoid borking https://readthedocs.org/projects/godot/ again, it's used by hundreds of users every day :)