Alright, I’ve updated the PEP, you can see a diff at https://github.com/python/peps/pull/1042 and I’ve updated the first post to have the latest text.
Major differences:
- Explicitly call out the
python-requires case as a motivation.
- Specify that yanking a file is not permanent, and that tooling has to be able to cope with a file being unyanked (and potentially yanked again in the future).
- Specify what will get logged to the journal for yanking or unyanking a file.
- This isn’t really part of the simple repository API, but I wanted to include it because I think it’s an important part of this feature.
- Expanded the section how consumers of the API should treat yanked files, both as installers and as mirrors.
- For installers, it takes @pganssle general approach above while also adding some specific recommendations.
- For mirrors it gives two options, depending on how that particular mirror wants to operate.
- Says that installers that do choose to use a yanked file, should emit a warning about the fact that they did. This is only a SHOULD so installers can choose to not do that if they want, but ideally they all will.
I’m pretty happy with the current state of this PEP now, I think it gives us a fairly powerful and general feature that projects can use to guide people away from releases that have major known issues, without all of the downsides of outright deleting files.
The only real open question in my mind, isn’t really specific to the simple repository API but rather a general question and then depending on the result of that, maybe a question for how to represent that in the journal.
Because of the nature of the simple repository API, yanking has to be indicated on a file by file basis but that doesn’t answer the question of conceptually what do project authors want to yank? Is it file by file? Is it entire releases? Both?
At first I was thinking of this feature that projects would yank files, but the more I think about it the more I think it might only make sense to yank entire releases. I think there are three major cases that can occur if we yank file by file:
- There is a sdist and 1 or more wheels, they are all the same version so they’re all equally acceptable.
- If you yank wheel(s), those yanked files will never be used, so it’s roughly the same as deleting because the sdist is always acceptable for anything the wheel is acceptable for, so an installer would end up using the wheel.
- If you yank the sdist, then the wheels will still be used by default, except on platforms where there aren’t wheels then the normal yanking semantics will come into play. It feels weird to me that in this case yanking or not will vary on a platform basis, and potentionally seems like a footgun for user confusion.
- There is no sdist, and only wheels.
- If there are multiple wheels that are acceptable for each platform, then this case is the same as the first sub bullet above.
- If there is only one wheel for a given platform, then the weird platform varying-ness still applies.
- There is only a sdist, and no wheels.
- Yanking the only file on a release is exactly the same as yanking the entire release, so there is no difference.
So I think that as a concept, it should be thought of as yanking an entire release, and just the implementation of the simple repository API means that gets represented on a file by file basis. In that case, I think the journal entry should be updated so it’s just yank release and unyank release and doesn’t specify a file at all, because it is all the files, but maybe mirroring software authors would find it more useful to still have it represented in the journal as if it was yanking file by file?
Another open question I think is if we’re yanking entire releases, should new uploads to that release be accepted? Or once a release is yanked should we treat it as locked in some way?
These aren’t exact fits for specifying in the simple repository API, but I think they’re important questions for actually implementing it, and we should probably specify it in the PEP.