Semantic Versioning #94

Closed
mauris opened this Issue May 1, 2013 · 15 comments

Comments

Projects
None yet
2 participants
@mauris

mauris commented May 1, 2013

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

This comment has been minimized.

Show comment Hide comment
@michelf

michelf May 1, 2013

Owner

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?

Owner

michelf commented May 1, 2013

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

This comment has been minimized.

Show comment Hide comment
@mauris

mauris May 2, 2013

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 commented May 2, 2013

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

This comment has been minimized.

Show comment Hide comment
@mauris

mauris May 2, 2013

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

mauris commented May 2, 2013

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

This comment has been minimized.

Show comment Hide comment
@michelf

michelf May 2, 2013

Owner

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.

Owner

michelf commented May 2, 2013

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

This comment has been minimized.

Show comment Hide comment
@michelf

michelf May 2, 2013

Owner

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.

Owner

michelf commented May 2, 2013

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

This comment has been minimized.

Show comment Hide comment
@mauris

mauris May 2, 2013

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.

mauris commented May 2, 2013

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

This comment has been minimized.

Show comment Hide comment
@michelf

michelf May 2, 2013

Owner

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.

Owner

michelf commented May 2, 2013

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

This comment has been minimized.

Show comment Hide comment
@mauris

mauris May 2, 2013

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 commented May 2, 2013

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

This comment has been minimized.

Show comment Hide comment
@mauris

mauris May 2, 2013

thephpdeveloper/Yaml#1

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

mauris commented May 2, 2013

thephpdeveloper/Yaml#1

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

@michelf

This comment has been minimized.

Show comment Hide comment
@michelf

michelf May 2, 2013

Owner

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.

Owner

michelf commented May 2, 2013

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.

@michelf michelf closed this May 2, 2013

@mauris

This comment has been minimized.

Show comment Hide comment
@mauris

mauris May 3, 2013

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".

mauris commented May 3, 2013

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

This comment has been minimized.

Show comment Hide comment
@michelf

michelf May 3, 2013

Owner

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.

Owner

michelf commented May 3, 2013

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

This comment has been minimized.

Show comment Hide comment
@mauris

mauris May 4, 2013

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?

mauris commented May 4, 2013

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

This comment has been minimized.

Show comment Hide comment
@michelf

michelf May 4, 2013

Owner

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.

Owner

michelf commented May 4, 2013

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.

@mauris

This comment has been minimized.

Show comment Hide comment
@mauris

mauris May 4, 2013

hmm, how about just doing that for every new Major-Minor version combination only? If not we will end up with a lot of releases and minor patches get released very slowly. This way it will be how I charted above.

Anyway, changes in patch numbers are only changes to internal APIs. So if there is a problem with a patch, we release another patch quickly.

That's also where Code Coverage, CI and unit testing comes hand in hand to ensure patches are "bug-proof".

mauris commented May 4, 2013

hmm, how about just doing that for every new Major-Minor version combination only? If not we will end up with a lot of releases and minor patches get released very slowly. This way it will be how I charted above.

Anyway, changes in patch numbers are only changes to internal APIs. So if there is a problem with a patch, we release another patch quickly.

That's also where Code Coverage, CI and unit testing comes hand in hand to ensure patches are "bug-proof".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment