Skip to content
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
Closed

"stable" appearing to track future release branches #3268

andrewgodwin opened this issue Nov 15, 2017 · 43 comments
Assignees
Labels

Comments

@andrewgodwin
Copy link

@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
Copy link
Member

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

@willingc
Copy link
Contributor

@willingc 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
Copy link
Author

@andrewgodwin 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
Copy link
Contributor

@agjohnson 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
Copy link
Author

@andrewgodwin 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
Copy link
Contributor

@willingc 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
Copy link
Member

@humitos 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
Copy link
Contributor

@agjohnson 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
Copy link
Author

@andrewgodwin andrewgodwin commented Nov 17, 2017

Cool, thanks for your help on this!

@humitos
Copy link
Member

@humitos 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: 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
Copy link
Contributor

@willingc 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
Copy link
Author

@andrewgodwin 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
Copy link
Member

@humitos 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
Copy link
Member

@humitos 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
Copy link
Author

@andrewgodwin andrewgodwin commented Nov 18, 2017

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

@humitos
Copy link
Member

@humitos 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
Copy link
Member

@humitos humitos commented Nov 29, 2017

Meh, wrong button clicked :/

@humitos humitos reopened this Nov 29, 2017
@andrewgodwin
Copy link
Author

@andrewgodwin 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
Copy link
Contributor

@willingc willingc commented Nov 29, 2017

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

@agjohnson
Copy link
Contributor

@agjohnson agjohnson commented Nov 29, 2017

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

@andrewgodwin
Copy link
Author

@andrewgodwin andrewgodwin commented Nov 29, 2017

Great! Thanks all.

@ericholscher
Copy link
Member

@ericholscher ericholscher commented Nov 29, 2017

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

@andrewgodwin
Copy link
Author

@andrewgodwin 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
Copy link
Member

@humitos 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
Copy link
Member

@ericholscher ericholscher commented Nov 30, 2017

@andrewgodwin
Copy link
Author

@andrewgodwin 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
Copy link
Member

@ericholscher 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
Copy link
Member

@ericholscher ericholscher commented Nov 30, 2017

Any build should fix it now though.

@ericholscher
Copy link
Member

@ericholscher ericholscher commented Nov 30, 2017

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

@andrewgodwin
Copy link
Author

@andrewgodwin andrewgodwin commented Nov 30, 2017

Ah, perfect, all fixed. Thanks!

@humitos
Copy link
Member

@humitos 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
Copy link
Member

@ericholscher 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
Copy link
Member

@ericholscher ericholscher commented Nov 30, 2017

I'll do a PR for that one.

@humitos
Copy link
Member

@humitos humitos commented Nov 30, 2017

Got it! Thanks for the exaplanation.

@akien-mga
Copy link
Contributor

@akien-mga 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
Copy link
Member

@stsewd 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
Copy link
Contributor

@akien-mga 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
Copy link
Contributor

@akien-mga 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
Copy link
Member

@humitos 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
Copy link
Contributor

@akien-mga 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
Copy link
Contributor

@akien-mga 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
Copy link
Member

@humitos 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
Copy link
Contributor

@akien-mga 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
Labels
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
8 participants