Use branch alias for calculating normalized version

[rob006]

Problem

While https://blog.packagist.com/composer-and-default-git-branches/ tried to improve the way how branches are handled, it changed one assumption (master branch have some special meaning) to another (default branch have some special meaning). As result it makes situation much worse for repositories where default branch is not used as development branch. For example for https://github.com/FriendsOfPHP/PHP-CS-Fixer default branch points to the last stable line (2.16.x), master branch (which is not default) represents future minor release (2.17.x), and there is also 3.0 branch for development of next major release. Before latest changes in version normalization, order of versions/branches looked something like this:

dev-master / 2.17.x-dev
3.0.x-dev
2.16.x-dev
v2.16.3
...
2.15.x-dev
v2.15.7
...

It is not perfect, but you could argue that putting main development branch on the top, before 3.0.x-dev, makes sense. But now order looks like this:

2.16.x-dev
3.0.x-dev
v2.16.3
v2.16.2
v2.16.1
v2.16.0
2.15.x-dev
v2.15.7
...
v0.1.0
dev-master / 2.17.x-dev

dev-master / 2.17.x-dev, which is main development branch, is at the end of versions list. Which kinda hides the most recent version at the end of versions list.

Solution

I suggest to use branch alias for resolving normalized version and do not put any special meaning for default branch if it has correct normalized version. Examples:

1. Default branch dev-master without any alias will be normalized to dev-master and put at the top of versions list (the same as now).
2. Default branch dev-master with alias 3.0.x-dev will be normalized to 3.0.9999999.9999999-dev and use this normalized version for positioning on list of versions. If 4.0.x-dev branch exists, it will be above 3.0.x-dev.
3. If someone is crazy enough: 3.0.x-dev branch with alias 2.0.x-dev will be normalized to 2.0.9999999.9999999-dev and put bellow any 3.* release/branch.

So for https://github.com/FriendsOfPHP/PHP-CS-Fixer we will have:

3.0.x-dev
dev-master / 2.17.x-dev
2.16.x-dev
v2.16.3
...
2.15.x-dev
v2.15.7
...

In this way ordering versions should be more natural.
This should also fix PUGX/badge-poser#342 if this normalized versions will be available as version_normalized in JSON with package data from API.

[stof]

version_normalized in the package.json must be the normalized version of what is in version according to composer/semver, otherwise it will break Composer itself. So branch aliases cannot be used there (an AliasPackage in composer, used to represent branch aliases, has its own version, and so its own normalized version).

The default branch of the repository does not have any special meaning in composer itself for dependency solving (the default branch is still used to get the uptodate funding info), as of Composer 2. As of Composer 2, the normalized version of dev-master is indeed dev-master, as the special handling of dev-master has been dropped.

If poser needs to be able to get details of the default branch of the repo, identifying it using "default-branch": true in the JSON is the way to go (and then, they can use the corresponding branch alias if they need it).

As far as Packagist is concerned, I think the branch alias should be taken into account for the sorting for non-comparable versions (i.e. dev-* versions for branches). for the case of 3.0.x-dev aliased as 2.0.x-dev, I suggest keeping the sorting based on 3.0.x-dev as this is already comparable (basically, I want to use the alias version only when comparing the main version does not make sense).
Then, there is the question whether the default branch should appear first in the list or no. We might indeed decide to apply this rule only when the default branch does not have a comparable version (including with the alias taken into account, maybe)