Rename the 'latest' build to something else

[embray]

Some of my users have been confused from time to time about the difference between "latest" and "stable". They aren't doing development on the project so to them there's no reason "latest" shouldn't be read as "latest release". I think I'd personally prefer to call it something like "dev" instead.

However, I'm not proposing changing the language for everyone, as I can see how it's fine for other projects.

So I think it should be possible to provide a custom name for the "latest" build that always points to master/trunk/etc.

The work recently done in #1354 looks like it might help make this easier. It would also provide a workaround for #534, and might also work as at least a bridge to #893. I'd be happy to look into providing an initial patch if it sounds like a good idea.

[gregmuellegger]

This is a little bigger task and I don't know if making this configurable will gain us a lot. In my eyes it's an actual feature to have one distinct name where I as a user can be sure that if I look at a URL containing "latest", that it's really the most up-to-date version of the project I look for. But I will leave the decision for this to @agjohnson and @ericholscher

I think you can emulate your desired behaviour by deactivating the "latest" build and only use the "stable" build. Or you enable builds for your master branch under the name "master". That's not as nice as "dev" but maybe less confusing for your users.

[embray]

In my eyes it's an actual feature to have one distinct name where I as a user can be sure that if I look at a URL containing "latest", that it's really the most up-to-date version of the project I look for.

From the perspective of readers of the documentation I don't think that's really important. The average user of my software doesn't know or care that the docs are hosted on RTD, and don't expect to find a common interface, in this regard, from one RTD site to the next. Moreover, the minority of users who do use development versions can understand the distinctions involved.

My thinking was that this could be done just as sort of an alias--still refer to it as the "latest" version internally, but allow a different name for display / URL purposes. I figured that would be simpler to implement than most alternatives but I'm sure I'm missing some subtleties.

Nevertheless, it's been my experience that many users, especially those who are not expert software developers, easily confuse "latest" with "stable".

[gregmuellegger]

Nevertheless, it's been my experience that many users, especially those who are not expert software developers, easily confuse "latest" with "stable".

True, that makes sense for documentation that is not about a library but an end user facing interface. Lets leave this open to the project lead to decide on how we go forward on this.

[embray]

True, that makes sense for documentation that is not about a library but an end user facing interface.

Library too--this comes up specifically in the context of the Astropy project; i.e. scientific users, many of whom need to work with scientific software libraries but are not "typical" software developers.

[ericholscher]

Agreed that 'latest' and 'stable' necessarily the best names. However, any name we choose will be confusing in some contexts, and I do think that having consistent naming across all projects is more important than having them be configurable.

There are a decent number of places in the codebase where we require a 'latest' version, and making it configurable would increase complexity in a lot of places without much real gain. We could definitely be documentating & explaining what the differences between the two are better though. We talk about it here: http://docs.readthedocs.org/en/latest/versions.html#how-we-envision-versions-working -- but it isn't exposed in the UI anywhere really.

[embray]

Yeah, documenting better in the RTD docs, while maybe useful for RTD users is not useful to readers of docs hosted on RTD.

I don't see what the advantage (in principle, not technically) is to 100% consistent naming across projects but I defer to your judgment on that.

The ideal solution to me would be able to host any branch of a repo as a "version" with whatever name I want to give it (i.e. #893). I thought this idea would be a simpler solution in the short term, but if that's undesirable #893 is the answer, if that's somehow more doable (which I'd also be willing to work on).

[stsewd]

Probably this #3481 is better to solve the problem.

[davidism]

Flask and Django both use the URL and label "dev" instead of "latest". I can say I've definitely been confused in the past when I land on "latest" by default on RTD.

[agjohnson]

I think momentum is pushing toward implementing this in #4001. I'm not sure if configuring latest will be an option, but I think we can have an alias for latest that allows us to keep internal representations, but allow public display to point to a different slug. Pushing this conversation to #4001.