Reviews are an important part of the Swift evolution process. All review feedback should be either on this forum thread or, if you would like to keep your feedback private, directly to me as the review manager by DM. When contacting the review manager directly, please put "SE-0536" in the subject line.
What goes into a review?
The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:
What is your evaluation of the proposal?
Is the problem being addressed significant enough to warrant a change to Swift?
Does this proposal fit well with the feel and direction of Swift?
If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
More information about the Swift evolution process is available at:
I'm confused by the registry key - since that's never computed by the server, why is it in this Results object? Where is that applicable? Is that only for --json output? In that case, maybe it's clearer if you add this into the section on --json instead
Pagination
For a given query string and constant pagination parameters, result ordering MUST be stable across requests in the same session. A client iterating offset += limit until offset >= total MUST visit every matching package exactly once and never visit the same package twice.
What is a "session" from the standpoint of the server? From the client, it makes sense. But the server has no way to identify that we're in the same "session" as we were before, unless I'm missing something.
Without that I do not understand how a server will ever fulfill this promise.
Have you considered after (being the identity of the last result in the previous page if navigating forward) and before (being the identity of the first result in the "after" page if navigating backwards) pagination rather than offset + limit? It's often much easier to support stable pagination server-side this way.
Another option would be to only rely on the Link header, so the server could decide on its own how to manage this & it could be opaque to the client.
Side note: Has there been an attempt to put together an example registry server implementing this endpoint? Might be a useful exercise.
I would like to suggest slightly improved clarity around when something is expected to be deterministic or allows for fuzzy matching within the scope of part of this API.
In particular, I think the qualifiers scope, author, and pkg should be explicitly deterministic, and not allow fuzzy matching, especially for the examples of filtering. My primary reasoning is that this can lead to unexpected expansions of filters or constraints on the search.
I wouldn't want to say this is a required feature of any implementation, but it should is one that I'd look for and use.
I suspect we might want to consider the same "it's always deterministic/not fuzzy" for when we use name as well.
In short - a fuzzy description, or fuzzy general (unscoped) query, is where it provides the most value, and the expansion effects are what we intentionally want to allow (although not mandate).