How do I change the packagist sticker for stable release?

Kim Stacks picture Kim Stacks · Nov 7, 2013 · Viewed 9.2k times · Source

This is my open source code I wrote.

https://github.com/simkimsia/UtilityBehaviors/blob/master/README.mdown

I have a No Stable Release from packagist.org

How do I go about having a Stable Release sticker from packagist?

Answer

Sven picture Sven · Nov 7, 2013

You have to tag your code with a version number.

git tag -a 0.0.0

That will declare the first stable version. If you worry about an all-zero version number, you can start with something like 0.0.1 if you want. Try to stick to semantic versioning if you can: http://semver.org. After that you should push the to the public repository, like git push --tags.

Note that you can use the whole array of stability labels in your tags. There is everything from alpha, beta, release candidate recognized by Composer. See http://getcomposer.org/doc/04-schema.md#version for info on how to create a version number.

Packagist will then scan your repository and process that tag, which is a "stable" release, and mark your package accordingly (even with the 0.0.0 version number - 0.x software is not different from 24.x software in terms of Composer/Packagist).

Edit 2016-07-14

Note that version numbers in semantic versioning are handled different if they start with 0.x.y. This does not affect tagging and releasing in any way, but it affects the way users can select and update your released software. Any software in the 0.x range is considered an incompatible if you release the next minor update 0.x+1. The Composer tilde operator ~ will not be disturbed by this: ~0.x (with any integer as x) will update to the next minor version. The caret operator will behave different: ^0.x or ^0.x.y will stay in the 0.x range and not go to any 0.x+1.y release.

The best way to counter this would be to start with 1.x versions, and use stability flags to indicate possible changes. You can use 1.0.0-alpha1 as your first release instead of 0.0.1, later releases may be 1.0.0-alpha2 for another "unstable" (read: API not finished/stable) release, then go to 1.0.0-beta1 for API-stable, but internally unfinished releases, then 1.0.0-rc1 for possibly API-stable, finished releases during final bugfixing phase, and then 1.0.0 for the final release. More bugfixes will be 1.0.1 and up, new features will be 1.1.0, incompatible API changes will be 2.0.0. Note that the first users may use ^1.0.0@beta as their version requirement, and as development progresses, will always get the newest update without the need to change their requirement (unless you break your API and force updates that way). This will never work if you go the 0.x route and then release the final product as 1.0.0, because you have at least the obvious incompatible update jump to 1.0.

It's hard to decide without future knowledge whether a package proves to be useful and creates a happy user base (who will benefit from a 1.0.0@alpha release tag), or if it is only an interesting experiment that nobody is using in production (a.k.a. 0.x).

My personal preference for internal private packages is to make them 1.0 from the start. I have to deal with several packages that started at 0.0.1 and are a bit nasty when updating because they are mature, but cannot go to 1.0 because of that incompatible version step, which would involve a lot of work in secondary packages.