Deal better with stable and pre-release package versions

[daveverwer]

Inspired by this conversation.

When building out the site I specifically looked at what Xcode will import if you paste in a git repository. It picks the latest, stable version of a package. For example, even though Alamofire has a 5.0.0-beta.7 release right now, Xcode shows 4.8.2 when importing it. I chose to match that with the site.

As you can see in the Twitter thread, that's not perfect.

[daveverwer]

Also transferring this comment from @jshier:

I'll report this as feedback as well, Xcode should really show you both too. Reported as FB6961625.

[daveverwer]

I've done some work on this today and I am now scraping both beta versions and stable versions from the git repository. The big question now comes down to how to best display it all.

There are four cases to consider:

1. Where none of the tags in the git repository are valid semantic versions.
2. Where the latest tagged semantic version is also the latest version of the package.
3. Where the package has never had a stable release, only beta releases.
4. Where the latest semantic version is a beta, but there is also a stable version.

I think the answers to the first two cases are fairly obvious, and the last two are less so.

Where none of the tags in the git repository are valid semantic versions

I think this is obvious, and it should look just like it does right now with no version displayed. Like this:

Where the latest tagged semantic version is also the latest version of the package.

I think this is also fairly obvious, and it should look just like it does right now. Like this:

Where the package has never had a stable release, only beta releases.

This is where things get a little bit interesting. In this situation we are dealing with repositories that have no stable versions at all. So, the only tags that are valid semantic versions have pre tags.

Xcode always selects the latest stable version when adding a package, so there's an argument to have some kind of visual difference to this in the search results. Maybe something like this?

It could be something else, but dimming the version number is an idea.

Where the latest semantic version is a beta, but there is also a stable version.

This is where things get really interesting. When there is a package that has in the past had a stable version, but that is now under development of a beta version.

When there is any stable version, Xcode will recommend and default to that version when you use it to add the package. You have to manually type in the beta version number if you want it.

Maybe it should look something like this?

I have all of the server side logic already implemented and this screenshot is actually from my local development version of the site, but I'd really love some opinions before deploying it.

Thanks!

[jshier]

One important thing to keep in mind is that the latest and stable versions, whatever they may be, may also have different minimum OS and Swift levels. For instance, Alamofire 4 still supports iOS 8+ and Swift 3.2+, which is far lower than Alamofire 5. So it seems that, if those are different (however you're detecting that), that all information from both should be displayed. In that case, perhaps vertical display would be better?

[daveverwer]

One important thing to keep in mind is that the latest and stable versions, whatever they may be, may also have different minimum OS and Swift levels.

Yes, but there are a couple of problems with this. First, I have yet to implement per version metadata 😀 It's on the list but it's not yet implemented.

Second, these search results are already getting really visually busy. I'm not sure I can get all of that metadata to be displayed in a visually clear way.

[jshier]

Then I think I like the last UI, as at least then it could be somewhat clear the metadata is for the latest version and not the stable one, but there will likely always be confusion. Perhaps being able to select between the two?

[cmtrounce]

The last UI is the best, and I think it provides the most useful information. By that point, people searching will have enough information about what the library does to make a judgment on whether to click through to the details page.

[daveverwer]

This is what I went with in the end:

If there is no version tag that is a semantic version:

If the latest version is stable, or if there is only a beta version and no stable version has ever been released:

If there is a beta version, but a stable version has been previously released:

The metadata below the version is from the latest commit on the default branch right now, but that's next on my list. I also came up with a way to make the search results look good with two sets of metadata so your wish may come true @jshier!

This is now live on the site.