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

Rename "/legacy" url to something else #2285

Open
rsyring opened this Issue Aug 7, 2017 · 7 comments

Comments

Projects
None yet
6 participants
@rsyring

rsyring commented Aug 7, 2017

Original concern and Donald's reply below:

My setup.py has been communicating with https://upload.pypi.org/legacy/ by default. Note the legacy part.

This is confusing, and it is essentially due to the fact there are two things here which are considered “legacy”. One is the legacy codebase/deployment that currently powers pypi.python.org which are are slowly replacing and migrating things over to the new, modern code base that powers pypi.org. The other thing is the actual upload API itself, which has stayed the same currently, but which I plan to replace at some point in the future. This API is also considered “legacy” (it just doesn’t have a replacement yet). So the legacy in https://upload.pypi.org/legacy/ has to do with the API rather than the location/deployment.

I probably should have named it something other than /legacy/, my goal was mostly that changing URLs is hard (it requires a bunch of documentation/updates in different packages and N years for that to percolate out) so since we were forcing people to change the URLs with the move from pypi.python.org to pypi.org, might as well get it all done at once. It might be reasonable to name it something else now, and just keep the /legacy/ around as an alias. I’m not sure if that adds or subtracts from the confusion, but if you think that would have helped you, please open a new issue on Warehouse.

FWIW, something like "/api/v1" seems reasonable. I do think "/legacy" is confusing and renaming it now will be less confusing than keeping it.

@dstufft

This comment has been minimized.

Show comment
Hide comment
@dstufft

dstufft Aug 7, 2017

Member

Probably if we do this, using v0 makes sense just to indicate this is some sort of weird not-designed API or something.

Member

dstufft commented Aug 7, 2017

Probably if we do this, using v0 makes sense just to indicate this is some sort of weird not-designed API or something.

@brainwane

This comment has been minimized.

Show comment
Hide comment
@brainwane

brainwane Feb 20, 2018

Member

@rsyring Thank you very much for suggesting this, and sorry for the slow response! I brought this issue up in a meeting of Warehouse developers today I want to walk you (and other Python developers reading this in the future) through what Warehouse's maintainers currently think about this question.

(For context: the folks working on Warehouse have gotten limited funding to concentrate on improving and deploying Warehouse, and have kicked off work towards our development roadmap -- the most urgent task is to improve Warehouse to the point where we can redirect pypi.python.org to pypi.org so the site is more sustainable and reliable.)

When I put this item on the meeting agenda, I was initially thinking: yes, it's currently a confusing URL, and as long as we're trying to get a lot of package maintainers to change their workflows, we should do this and coordinate with the distribution tools/docs folks so it changes everywhere at once.

As we were talking today, two counterarguments came up.

  • in the past, we've already changed the URL once, and caused substantial client support confusion and frustration.
  • We could make an alias, but that might just lead to more confusion in the long run, since /legacy would still be around and working, and some clients would use it.

So this needs further thought. And since this issue isn't a blocker to shutting down the old site, I've moved it to a future milestone.

Thanks and sorry again for the wait.

Member

brainwane commented Feb 20, 2018

@rsyring Thank you very much for suggesting this, and sorry for the slow response! I brought this issue up in a meeting of Warehouse developers today I want to walk you (and other Python developers reading this in the future) through what Warehouse's maintainers currently think about this question.

(For context: the folks working on Warehouse have gotten limited funding to concentrate on improving and deploying Warehouse, and have kicked off work towards our development roadmap -- the most urgent task is to improve Warehouse to the point where we can redirect pypi.python.org to pypi.org so the site is more sustainable and reliable.)

When I put this item on the meeting agenda, I was initially thinking: yes, it's currently a confusing URL, and as long as we're trying to get a lot of package maintainers to change their workflows, we should do this and coordinate with the distribution tools/docs folks so it changes everywhere at once.

As we were talking today, two counterarguments came up.

  • in the past, we've already changed the URL once, and caused substantial client support confusion and frustration.
  • We could make an alias, but that might just lead to more confusion in the long run, since /legacy would still be around and working, and some clients would use it.

So this needs further thought. And since this issue isn't a blocker to shutting down the old site, I've moved it to a future milestone.

Thanks and sorry again for the wait.

@ncoghlan

This comment has been minimized.

Show comment
Hide comment
@ncoghlan

ncoghlan Feb 21, 2018

Member

FWIW, I added an explanation of the legacy in the URL to the end of https://packaging.python.org/guides/migrating-to-pypi-org/#publishing-releases when consolidating the two distinct sets of migration guidance that we had.

Note that our main recommendation is to upgrade twine, setuptools, and/or Python to get an updated default setting, not to adjust your config directly.

So while we could add the v0 alias, the exact URL is already mostly hidden from users that aren't stuck using older upload clients, and it isn't clear yet whether Warehouse is going to use API versioning in the URL, or instead provide graceful evolution of the individual endpoints.

Member

ncoghlan commented Feb 21, 2018

FWIW, I added an explanation of the legacy in the URL to the end of https://packaging.python.org/guides/migrating-to-pypi-org/#publishing-releases when consolidating the two distinct sets of migration guidance that we had.

Note that our main recommendation is to upgrade twine, setuptools, and/or Python to get an updated default setting, not to adjust your config directly.

So while we could add the v0 alias, the exact URL is already mostly hidden from users that aren't stuck using older upload clients, and it isn't clear yet whether Warehouse is going to use API versioning in the URL, or instead provide graceful evolution of the individual endpoints.

@ncoghlan

This comment has been minimized.

Show comment
Hide comment
@ncoghlan

ncoghlan Apr 27, 2018

Member

pypa/python-packaging-user-guide#479 highlights a remaining case where the "legacy" in the URL is visible: when setting up use of test.pypi.org.

That currently looks like:

$ twine upload --repository-url https://test.pypi.org/legacy/ dist/* 

I think part of the problem in that case is that the phrasing of the legacy URL explanation at https://packaging.python.org/guides/using-testpypi/#using-test-pypi is confusing, but I also think it would likely be clearer with v1 as originally suggested above:

$ twine upload --repository-url https://test.pypi.org/v1/ dist/* 

Alternatively, we could stick an -api suffix in there to make it clear that the versioning info relates to the specific API, not the service itself:

$ twine upload --repository-url https://test.pypi.org/v1-api/ dist/* 
$ twine upload --repository-url https://test.pypi.org/legacy-api/ dist/* 

While the v0 idea was interesting, I think v1 or v1-api would be clearer, as we'll be calling the new upload API the "Version 2 upload API" for the sake of discussing the design, even if it doesn't actually end up with "v2" in the related URL endpoints.

Member

ncoghlan commented Apr 27, 2018

pypa/python-packaging-user-guide#479 highlights a remaining case where the "legacy" in the URL is visible: when setting up use of test.pypi.org.

That currently looks like:

$ twine upload --repository-url https://test.pypi.org/legacy/ dist/* 

I think part of the problem in that case is that the phrasing of the legacy URL explanation at https://packaging.python.org/guides/using-testpypi/#using-test-pypi is confusing, but I also think it would likely be clearer with v1 as originally suggested above:

$ twine upload --repository-url https://test.pypi.org/v1/ dist/* 

Alternatively, we could stick an -api suffix in there to make it clear that the versioning info relates to the specific API, not the service itself:

$ twine upload --repository-url https://test.pypi.org/v1-api/ dist/* 
$ twine upload --repository-url https://test.pypi.org/legacy-api/ dist/* 

While the v0 idea was interesting, I think v1 or v1-api would be clearer, as we'll be calling the new upload API the "Version 2 upload API" for the sake of discussing the design, even if it doesn't actually end up with "v2" in the related URL endpoints.

@theacodes

This comment has been minimized.

Show comment
Hide comment
@theacodes

theacodes May 4, 2018

Member

Sounds good to me- so all we really need to do here is change /legacy to /v1-api and keep an alias for /legacy so that no one breaks?

Member

theacodes commented May 4, 2018

Sounds good to me- so all we really need to do here is change /legacy to /v1-api and keep an alias for /legacy so that no one breaks?

@theacodes

This comment has been minimized.

Show comment
Hide comment
@theacodes

theacodes May 4, 2018

Member

Or more simply add a /v1-api alias for /legacy and leave /legacy alone.

I'm happy to make this change, but I actually can't find where this is configured.

Member

theacodes commented May 4, 2018

Or more simply add a /v1-api alias for /legacy and leave /legacy alone.

I'm happy to make this change, but I actually can't find where this is configured.

@pradyunsg

This comment has been minimized.

Show comment
Hide comment
@pradyunsg

pradyunsg May 4, 2018

Member

It seems to me to be at the following (but I've been wrong with regards to this codebase before):

def add_legacy_action_route(config, name, action, **kwargs):
custom_predicates = kwargs.pop("custom_predicates", [])
custom_predicates += [pypi_action(action)]
config.add_route(
name,
"/legacy/",
custom_predicates=custom_predicates,
**kwargs
)

Member

pradyunsg commented May 4, 2018

It seems to me to be at the following (but I've been wrong with regards to this codebase before):

def add_legacy_action_route(config, name, action, **kwargs):
custom_predicates = kwargs.pop("custom_predicates", [])
custom_predicates += [pypi_action(action)]
config.add_route(
name,
"/legacy/",
custom_predicates=custom_predicates,
**kwargs
)

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