New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

"stable" appearing to track future release branches #3268

Closed
andrewgodwin opened this Issue Nov 15, 2017 · 43 comments

Comments

Projects
None yet
8 participants
@andrewgodwin

andrewgodwin commented Nov 15, 2017

Details

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

This comment has been minimized.

Member

RichardLitt commented Nov 15, 2017

> git ls-remote --tags git@github.com:django/channels.git

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

@RichardLitt RichardLitt added the Bug label Nov 15, 2017

@willingc

This comment has been minimized.

Contributor

willingc commented Nov 15, 2017

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

screenshot 2017-11-15 14 19 45

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.

screenshot 2017-11-15 14 20 21

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

This comment has been minimized.

andrewgodwin commented Nov 16, 2017

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:

snip1
snip2

@agjohnson

This comment has been minimized.

Contributor

agjohnson commented Nov 16, 2017

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.

@agjohnson agjohnson added this to the Build stability milestone Nov 16, 2017

@andrewgodwin

This comment has been minimized.

andrewgodwin commented Nov 16, 2017

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

This comment has been minimized.

Contributor

willingc commented Nov 16, 2017

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

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
screenshot 2017-11-16 10 10 20
UI
screenshot 2017-11-16 10 14 16

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

This comment has been minimized.

Member

humitos commented Nov 16, 2017

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 #3260

Seems it's not deployed yet.

It shouldn't be related with andrew's issue regarding the stable version.

@agjohnson

This comment has been minimized.

Contributor

agjohnson commented Nov 16, 2017

@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

This comment has been minimized.

andrewgodwin commented Nov 17, 2017

Cool, thanks for your help on this!

@humitos

This comment has been minimized.

Member

humitos commented Nov 17, 2017

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:

def determine_stable_version(version_list):
"""Determine a stable version for version list
Takes a list of ``Version`` model instances and returns the version
instance which can be considered the most recent stable one. It will return
``None`` if there is no stable version in the list.
"""
versions = sort_versions(version_list)
versions = [
(version_obj, comparable)
for version_obj, comparable in versions
if not comparable.is_prerelease]
if versions:
version_obj, comparable = versions[0]
return version_obj
return None

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

This comment has been minimized.

Contributor

willingc commented Nov 17, 2017

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

This comment has been minimized.

andrewgodwin commented Nov 17, 2017

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

This comment has been minimized.

Member

humitos commented Nov 17, 2017

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

This comment has been minimized.

Member

humitos commented Nov 17, 2017

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

This comment has been minimized.

andrewgodwin commented Nov 18, 2017

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

@humitos

This comment has been minimized.

Member

humitos commented Nov 29, 2017

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 07053be), 2.0 (pointing to the branch 2.0) and 1.1.8 (pointing to 07053be) as active versions, when I open

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

I see this message:

captura de pantalla_2017-11-29_13-55-08

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 humitos closed this Nov 29, 2017

@humitos

This comment has been minimized.

Member

humitos commented Nov 29, 2017

Meh, wrong button clicked :/

@humitos humitos reopened this Nov 29, 2017

@andrewgodwin

This comment has been minimized.

andrewgodwin commented Nov 29, 2017

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

This comment has been minimized.

Contributor

willingc commented Nov 29, 2017

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

@agjohnson

This comment has been minimized.

Contributor

agjohnson commented Nov 29, 2017

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

@andrewgodwin

This comment has been minimized.

andrewgodwin commented Nov 29, 2017

Great! Thanks all.

@ericholscher

This comment has been minimized.

Member

ericholscher commented Nov 29, 2017

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

@andrewgodwin

This comment has been minimized.

andrewgodwin commented Nov 30, 2017

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

This comment has been minimized.

Member

humitos commented Nov 30, 2017

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

captura de pantalla_2017-11-29_21-33-07

I will try to take a look at this tomorrow.

@ericholscher

This comment has been minimized.

Member

ericholscher commented Nov 30, 2017

@andrewgodwin

This comment has been minimized.

andrewgodwin commented Nov 30, 2017

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 comment has been minimized.

Member

ericholscher commented Nov 30, 2017

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

This comment has been minimized.

Member

ericholscher commented Nov 30, 2017

Any build should fix it now though.

@ericholscher

This comment has been minimized.

Member

ericholscher commented Nov 30, 2017

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

@andrewgodwin

This comment has been minimized.

andrewgodwin commented Nov 30, 2017

Ah, perfect, all fixed. Thanks!

@humitos

This comment has been minimized.

Member

humitos commented Nov 30, 2017

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

This comment has been minimized.

Member

ericholscher commented Nov 30, 2017

@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

This comment has been minimized.

Member

ericholscher commented Nov 30, 2017

I'll do a PR for that one.

@humitos

This comment has been minimized.

Member

humitos commented Nov 30, 2017

Got it! Thanks for the exaplanation.

@akien-mga

This comment has been minimized.

Contributor

akien-mga commented Jan 16, 2018

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

This comment has been minimized.

Member

stsewd commented Jan 16, 2018

@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

This comment has been minimized.

Contributor

akien-mga commented Jan 16, 2018

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

This comment has been minimized.

Contributor

akien-mga commented Jan 16, 2018

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

This comment has been minimized.

Member

humitos commented Jan 16, 2018

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

This comment has been minimized.

Contributor

akien-mga commented Jan 16, 2018

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

This comment has been minimized.

Contributor

akien-mga commented Jan 16, 2018

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

This comment has been minimized.

Member

humitos commented Jan 17, 2018

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

This comment has been minimized.

Contributor

akien-mga commented Jan 17, 2018

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 :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment