Add branch-alias for master branch

[Seldaek]

This allows requiring the package as ^3@dev which is safer than dev-master in the long run.

[clue]

@Seldaek Thanks for bringing this up! Love to see more usage of our upcoming promise v3 and agree that having a safer way to test out this version sounds promising (sorry).

That said, I wonder how this will affect the development branch in the longer run. It's my understanding this branch alias would exist until we tag v3 at which point it would be removed again? How does this affect your plans to rely on this development version? Would this considered to be breaking? Also, I'm sure v3 will still see a number of changes that may or may not break your usage, so I wonder if we should endorse relying on it at the moment or if targeting it by using its commit hash would be safer?

I think we all agree that it's about time we get the promise v3 out! We've had some discussions this week about this already and we're trying to get this out as soon as possible.

[Seldaek]

Don't worry I have no intent on shipping a dev version of this lib in Composer, I'm not insane :D

There is literally no downside I can think of of adding a branch-alias though. It's not only useful pre-release, it's also useful later. Composer has one too for example https://github.com/composer/composer/blob/main/composer.json#L62 - it now allows people to require ^2.3@dev and get a pre-release, but the good thing is that once we released 2.3.0 it keeps targetting the latest dev version so as long as main branch keeps the alias it would be installable as ^2.3@dev. But once main branch starts targetting 3.0, we'd change the branch-alias to 3.0-dev or 3.x-dev, and the ^2.3@dev require will downgrade from dev-main (aliased) to whatever the latest 2.x && >=2.3.0 stable release is, no breaking change ensuing.

On the other hand if you don't have a branch-alias, you force people to require dev-main, and then when you switch to target 3.0 people requiring dev-main are caught with their pants down and an update will get them breaking changes if they aren't very careful.

Probably I should make sure this is better explained in https://getcomposer.org/doc/articles/aliases.md#branch-alias

[clue]

Don't worry I have no intent on shipping a dev version of this lib in Composer, I'm not insane :D

I'm relieved! 😃

I agree that being able to install ^3@dev is way more stable than only targeting dev-master. At the same time, I'm not sure using a branch alias is the way go here, but would instead propose renaming our master branch to 3.x instead.

This way, the branch name would be in line with the other branches (2.x and 1.x). It also avoids any future breakage once we would potentially start working on v4 at which we would have to rename this branch anyway.

This also allows you to target release ranges like ^2@dev even if we remove the branch at some point in the future (no plans to do so at the moment) as it would automatically pick the latest release automatically in this case.

IMHO this way we would provide everything you've suggested without causing any maintenance work down the line (see also reactphp/reactphp#343 where we've decided to remove the branch aliases – though admittedly the ecosystem looked entirely different back then).

What do you think about this?

[Seldaek]

I just think offering only dev-master as option for requiring dev packages is preventing your users from using sane constraints and thus encouraging people to shoot themselves in the foot.

But for sure using a branch-alias is merely a way to make it look as if you had a versioned branch even though it is named, so using versioned branches directly is totally fine too. It's just more work I find (you seem to think it's easier to rename the branch than the branch-alias, I guess it's down to workflow/habit mostly), and depending on the project renaming the default branch often is not so practical, so branch-alias is there if you need it.

[clue]

Agreed, definitely valuable to have both options depending on requirements! Good discussion, really helps moving this forward, thank you very much!