Semantic Versioning

[mauris]

Thank you @michelf for progressing php-markdown forward by making it a composer package and refactored much of the classes.

I'd like to take this opportunity to suggest that we take up Semantic Versioning with php-markdown.

Semantic Versioning helps developers better manage versions of dependencies by using the format X.Y.Z. The link above describes in details what does the numbers in the version number will represent and when will they change.

This will greatly help php-markdown to brace any BC in the future if required and developers will be able to make better decisions with any updates.

[michelf]

There's already a versioning policy inspired from Semantic Versioning here:
https://github.com/michelf/php-markdown/blob/lib/Readme.md#public-api-and-versioning-policy

Is there anything you wish would be different about it?

[mauris]

The versioning policy sounds good, but it seems to be not implemented. This is based on the new tags created from April 2013 onwards (in 1.3.x). Most of the version numbering are in the form of 1.3-beta1 and ultimately 1.3.

Can we use back the X.Y.Z versioning as described in the policy?

I understand where you're doing with the beta and rc labels. As described in the Composer manual, what we can do is to append the labels behind: 1.3.3-beta2.

[mauris]

Also, instead of creating an alias for the branch, you can create a working branch and name it the version you're working on.

Take a look at my slides for such a flow: https://speakerdeck.com/mauris/github-project-flow

[michelf]

Are you simply trying to say that I should have used 1.3.0 instead of 1.3? I tend to see them as the same thing.

As for working branches, if I were to preserve the precedent established with 'master' and 'extra', I'd have to name the working branch 'lib' while the stable branch would be called 'lib-stable'. That might be a good idea.

[michelf]

Ah, I see what you mean with the working branch. It's about Composer and Packagist. I got confused, I'm not sure exactly where it relates to your slides though, your working branch is called 'develop', not 1.2.x.

[mauris]

I use develop as a working branch, a branch which I will commit unstable / WIP code for an upcoming release. I use develop because I tend to keep a single linear working branch, and let it merge with master to produce a version. Then I use tags to control the versions appropriately. That way, master will always contain commits of all the tagged releases. However, since we are working with multiple versions concurrently, we can name the working branch to be 1.3 instead of develop.

Looking at your current tags, I'd name them the following:

Current	Recommended
1.3	1.3.6
1.3-rc2	1.3.5-rc2
1.3-rc1	1.3.4-rc1
1.3-beta5	1.3.3-beta5
1.3-beta4	1.3.2-beta4
1.3-beta2	1.3.1-beta2
1.3-beta1	1.3.0-beta1

So what happens is that if I were to use php-markdown in Composer like this:

{
    "require": {
        "michelf/php-markdown": "1.3.*"
    }
}

I'd be telling Composer to use the latest version of PHP Markdown 1.3. From 1.3.0-beta1, I can easily upgrade to 1.3.6 stable without any problem by running composer update because according to Semantic Versioning, the patch number is define as a release that modifies the library such that it wouldn't affect the public API.

[michelf]

Ok. I see what you mean, but at the same time I find your "recommended" versioning scheme completely non-sensial.

Alpha, beta, or rc versions are pre-release versions are meant to gather feedback about new features and bugs. If I find a design error, I'll fix it. If that breaks compatibility with the previous beta, then so be it. That's the whole point of having a beta cycle. I can't guaranty a stable feature set nor a backward-comptabile API between pre-release versions: they're meant to test things prior the official release, they are not stable.

If you consider them as part of the normal Semantic Versioning flow (as you seem to be doing) I'd have to increment the major version once in a while in the beta cycle (we'd probably be at version 5.0.0. right now). Incrementing the minor version is misleading because those are not patches.

[mauris]

Take a look at part 7, 8 and 9 of semver's specifications. They describe what Patch, Minor and Major version numbers define to be.

I see where you're coming from with your beta cycle. IMHO beta cycles are a matter of the past, especially with CI and PSR specs coming along gaining popularity these days. For repositories on my end, I consider all tagged commits with X.Y.Z versioning format to be stable releases and I quickly release small patches and improvement as I go. If the tag contains an unstable release, I'd call it e.g. X.Y.Z-alpha1 . My versions will always have X.Y.Z and they are incremented appropriately as I release.

I perform Github Pull Requests as I go to manage features. At each pull request from my working to master branch, I review all the commits and changes I've made and see which version number I should be incrementing (of course planned ahead).

[mauris]

mauris/Yaml#1

That's a sample pull request that I make to manage features and review changes prior to releases.

[michelf]

I'll consider setting the patch version to zero instead of nothing for the next minor version since that's what other packages on Packagist are doing (looking at Symphony and Zend Framework right now). But I don't think your numbering scheme makes much sense for pre-release versions.

[mauris]

I understand your flow better now.

Maybe append the ".0" for the current "1.3" stable?

So to clarify, php-markdown's flow is as such (for example):

1.3-alpha1 --->--- 1.3-alpha2 --->--- 1.3-beta1 --->--- 1.3-beta2 --->--- 1.3-beta3 --->--- 1.3-rc1 --->--- 1.3-rc2 --->--- 1.3.0 --->--- 1.3.1 ... etc
                 1.4-alpha1 --->--- 1.4-beta1 --->--- 1.4-beta2 --->--- 1.4-rc1 --->--- 1.4.0 --->--- 1.4.1 --->--- 1.4.2 ... etc

In such case, this is a better flow for "setting features as we code".

[michelf]

Maybe append the ".0" for the current "1.3" stable?

Well, it's too late for that now. As I said, I might do it for 1.4 (which would be 1.4.0), although I'm not sure it changes anything.

You didn't get the flow right either.

The idea is simply that if the number only has a major and minor, the patch version number is inferred to be zero. So if you see 1.3, it's the same thing as 1.3.0. And if you see 1.3-beta1, it's synonym with 1.3.0-beta1. I see now that omitting the patch number does not conform to the semantic versioning spec mentioned above, but it remains that it's a rather common way to assign version numbers.

[mauris]

So you mean to say that if we have patch release 1.3.1 for 1.3.0, we will still go through 1.3.1-beta1, 1.3.1-beta2 etc?

[michelf]

Yes, that's a possibility. I'll do that if I suspect the change might have created bugs elsewhere and it needs some testing. A beta version basically means please help me find bugs before I declare it stable.