Consistent version format #3504

stsewd · 2018-01-11T18:15:52Z

This closes #2357

A time ago travis failed, so this #3402 was proposed. Now while looking at #2357 I think we only need to return a single value (a version only have a single unique slug).

The js, didn't break because of some weird js implicit cast.

var currentURL = window.location.pathname.replace('rtfd', ['hi'])
console.log(currentURL)
// This works!

But as mentioned on the spec, must be a string not a list https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace.

Note: Thanks @lethosor for his initial work on this lethosor@7d84130

stsewd · 2018-01-11T18:17:10Z

Hope the tests don't panic!

stsewd · 2018-01-11T18:23:38Z

The tests failed, should update the tests or put this how was initially and change the js instead?

humitos

The problem I see making this as it should be is that we don't know who relis on this code (since it's accessed by javascript). So, I don't personally feel comfortable on changing it because I can't be sure that everything will continue working.

So, I'd say that we need to fix our Python tests for this, make some manual QA on different pages to see how the JS is affected and check that everything continue working and finally ask @agjohnson or @ericholscher if this won't blow up something else :)

humitos · 2018-02-15T22:41:51Z

readthedocs/restapi/views/footer_views.py

@@ -43,7 +43,7 @@ def get_version_compare_data(project, base_version=None):
    }
    if highest_version_obj:
        ret_val['url'] = highest_version_obj.get_absolute_url()
-        ret_val['slug'] = (highest_version_obj.slug,)
+        ret_val['slug'] = highest_version_obj.slug


This should be a single item. We were already biten by this issue and I saw a couple of drawbacks when changing this, and finally it stayed as it was (like a tuple).

I agree that this should be a single item.

Technically, this changes a public API endpoint response which would involve a major rev of the API (ugh, one of the few downsides of semver). If instead we classify it as a bugfix, then perhaps it's ok.

Do we have any idea why it was an array instead of a simple string? This appears to date back to at least #1499 when the v2 footer API was added. Do we think it was a bug the whole time? There was additional discussion in #3394 (comment).

stsewd · 2018-02-16T16:55:57Z

@humitos I update just one test file and everything is green now :). I think the only part this was used was on the banner and footer.

humitos · 2018-02-20T17:11:19Z

@davidfischer can you take a look at this PR? The Python code seems to be correct, but since there is a Javascript object that is different now in the response I want to be sure that this won't break other possible usages of this.

Not sure how to know this, though. So, maybe you know better :)

davidfischer · 2018-03-05T19:03:54Z

Sorry I missed this. I'm looking at it now.

davidfischer

From our functionality, this appears to be ok. However, I don't think I have the insight to know who is relying on this API endpoint.

I hate passing the buck, but I think @agjohnson or @ericholscher have to chime in.

davidfischer · 2018-03-05T19:24:38Z

readthedocs/restapi/views/footer_views.py

@@ -43,7 +43,7 @@ def get_version_compare_data(project, base_version=None):
    }
    if highest_version_obj:
        ret_val['url'] = highest_version_obj.get_absolute_url()
-        ret_val['slug'] = (highest_version_obj.slug,)
+        ret_val['slug'] = highest_version_obj.slug


I agree that this should be a single item.

Technically, this changes a public API endpoint response which would involve a major rev of the API (ugh, one of the few downsides of semver). If instead we classify it as a bugfix, then perhaps it's ok.

Do we have any idea why it was an array instead of a simple string? This appears to date back to at least #1499 when the v2 footer API was added. Do we think it was a bug the whole time? There was additional discussion in #3394 (comment).

ericholscher · 2018-03-06T01:14:26Z

The footer API is an internal API, so it should be OK to change how it works, as long as the client code changes too.

The main tricky thing with JS is that sometimes we are shipping the JS with each build, so we have to support older versions with embedded JS. This client code comes from the server though, so I think this change should be 👍.

The best way to test this is to build a local docset with master, then another docset with this branch. Then see if both work with the branch's JS.

ericholscher · 2018-03-06T01:15:31Z

I believe this is blocked on our inability to build our JS artifacts though, unless that has been resolved. We need to ship the Python & JS code at the same time.

humitos · 2018-03-23T17:07:49Z

readthedocs/core/static-src/core/js/doc-embed/version-compare.js

@@ -23,7 +23,7 @@ function init(data) {
    warning
      .find('a')
      .attr('href', currentURL)
-      .text(data.version);
+      .text(data.slug);


This seems to render a different value, right?

What's is version and what's slug here?

Is version used in another places? We should check that we can still access it now it's not a tuple anymore.

What's is version and what's slug here?

I think your past self alreay answer that question 😄 #2357 (comment). Also #2357 (comment)

I did a grep and it is used here:

https://github.com/rtfd/readthedocs.org/blob/c5d102a4b119e191fd6a7ea201c776e84dd177f8/readthedocs/core/static-src/core/js/doc-embed/search.js#L16

But again thanks to the implicit cast of js everything was good (at the end everyone was expecting a string here p:)

stsewd · 2018-04-18T08:58:27Z

Removing the blocking label since #3691 was closed

ericholscher · 2018-05-24T20:26:50Z

This has bothered me for ages. Will your work around the version comparison & Sphinx extension depend on this @humitos? I think it looks ready to merge from my perspective.

humitos · 2018-05-24T21:00:49Z

@ericholscher no, I don't think this will affect my work.

I'm merging it since you all agree with this changes and looks solid to me also.

Thank you all!

RichardLitt added the PR: work in progress Pull request is not ready for full review label Jan 11, 2018

humitos reviewed Feb 15, 2018

View reviewed changes

stsewd added 2 commits February 16, 2018 11:34

Return a single slug

d4af78c

Display version slug

a6c89d1

stsewd force-pushed the consistent-version-format branch from c51a325 to a6c89d1 Compare February 16, 2018 16:35

Update tests

3250b32

humitos added PR: ready for review and removed PR: work in progress Pull request is not ready for full review labels Feb 20, 2018

RichardLitt requested a review from davidfischer February 21, 2018 19:04

davidfischer reviewed Mar 5, 2018

View reviewed changes

RichardLitt requested a review from ericholscher March 5, 2018 20:32

RichardLitt added the Status: blocked Issue is blocked on another issue label Mar 6, 2018

humitos reviewed Mar 23, 2018

View reviewed changes

stsewd removed the Status: blocked Issue is blocked on another issue label Apr 18, 2018

humitos merged commit 15972f1 into readthedocs:master May 24, 2018

stsewd deleted the consistent-version-format branch May 24, 2018 22:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Consistent version format #3504

Consistent version format #3504

stsewd commented Jan 11, 2018

stsewd commented Jan 11, 2018

stsewd commented Jan 11, 2018

humitos left a comment

humitos Feb 15, 2018

davidfischer Mar 5, 2018

stsewd commented Feb 16, 2018

humitos commented Feb 20, 2018

davidfischer commented Mar 5, 2018

davidfischer left a comment

davidfischer Mar 5, 2018

ericholscher commented Mar 6, 2018 •

edited

Loading

ericholscher commented Mar 6, 2018

humitos Mar 23, 2018

humitos Mar 23, 2018

stsewd Mar 23, 2018 •

edited

Loading

stsewd commented Apr 18, 2018

ericholscher commented May 24, 2018

humitos commented May 24, 2018

Consistent version format #3504

Consistent version format #3504

Conversation

stsewd commented Jan 11, 2018

stsewd commented Jan 11, 2018

stsewd commented Jan 11, 2018

humitos left a comment

Choose a reason for hiding this comment

humitos Feb 15, 2018

Choose a reason for hiding this comment

davidfischer Mar 5, 2018

Choose a reason for hiding this comment

stsewd commented Feb 16, 2018

humitos commented Feb 20, 2018

davidfischer commented Mar 5, 2018

davidfischer left a comment

Choose a reason for hiding this comment

davidfischer Mar 5, 2018

Choose a reason for hiding this comment

ericholscher commented Mar 6, 2018 • edited Loading

ericholscher commented Mar 6, 2018

humitos Mar 23, 2018

Choose a reason for hiding this comment

humitos Mar 23, 2018

Choose a reason for hiding this comment

stsewd Mar 23, 2018 • edited Loading

Choose a reason for hiding this comment

stsewd commented Apr 18, 2018

ericholscher commented May 24, 2018

humitos commented May 24, 2018

ericholscher commented Mar 6, 2018 •

edited

Loading

stsewd Mar 23, 2018 •

edited

Loading