search

zzzprojects / html-agility-pack

Html Agility Pack (HAP) is a free and open-source HTML parser written in C# to read/write DOM and supports plain XPATH or XSLT. It is a .NET code library that allows you to parse "out of the web" HTML files.
https://html-agility-pack.net
MIT License
2.65k stars 376 forks source link

Follow semantic versioning #74

Open atifaziz opened 7 years ago

atifaziz commented 7 years ago

Looking at the history/changes between v1.5.1 and v1.5.6-beta2, it seems that there have been bug fixes and enhancements (like in 3b96a9ec20c55591e411844210ee03c9937eefcc and f99b05a979434c9b054bea04ebcf98f488969cde) yet only the patch version has been incremented in all cases. Conventionally, the patch version should be incremented for backward compatible bug fixes and the minor version incremented for enhancements. If someone takes a dependency on HtmlAgilityPack, it's important to be able to assess if a release or upgrade is expected to be a pure patch or not. The project should follow semantic versioning for all the various reasons listed in the Semantic Versioning specification.

JonathanMagnan commented 7 years ago

Hello atifaziz,

I understand your point but unfortunately, I don’t think that will happen yet.

Unlike some other company, we release very often. Very often also we introduce small change that are not really backward compatible.

By following this rule, the project https://github.com/zzzprojects/EntityFramework-Plus/releases would have been probably in version 30.x.y

As I understand this semantic is important for your side to understand what kind of change you could expect, I prefer at this moment to keep it simple on my side and not doing it the conventional way.

Best Regards,

Jonathan

cptjazz commented 7 years ago

If you manage the dependencies for larger projects with NuGet this is crucial. If you follow semver correctly, NuGet will "protect" you from installing stuff that will break binary compatibility. On the other hand, it will correctly pull in dependencies when you update a package.

I for one think a version like "30.x.y" is nothing to be afraid of -- if it correctly reflects the changes in the version number.

atifaziz commented 7 years ago

@cptjazz Couldn't agree more.

@JonathanMagnan:

we release very often

That's a great thing. :+1:

Very often also we introduce small change that are not really backward compatible.

That's not so good, especially if you're not changing the major version number.

By following this rule…releases would have been probably in version 30.x.y

There's nothing wrong with a minor or patch version being at 30 or 100 for that matter. If the major version is at 30 then it means 30 releases of the software with breaking changes or significant redesign, and that can't be a good thing for the project or its users.

semantic is important for your side

This is not to favour my personal setup or mission but an industry practice. As @cptjazz also pointed out, it affects anyone using NuGet as upgrade policies are based on package authors following semantic versioning. If I build a library on top of HtmlAgilityPack, it affects everyone up the chain, whoever that may be, an app or yet another package.

For a real example of how HtmlAgilityPack broke things in the past, see atifaziz/Fizzler#56.

I prefer at this moment to keep it simple on my side and not doing it the conventional way.

I understand except you're making your life easy but difficult for the users of HtmlAgilityPack and all other folks taking a direct or an indirect dependency. Rather than thinking & discussing in subjective terms and views (i.e. my way or your way), we should raise the arguments to being objective and talk in terms of pros and cons (the highway 😆).

One way to continue to release often is to maintain two streams/branches of development:

If you make the bug fix in 2.0, back-port to 1.6.x. If the fix is made in some 1.6.x instead, then forward-port to 2.0. If back-porting a fix isn't trivial and is going to slow you down considerably then you can choose not to back-port yourself at all. Eventually, if all the great fixes are going into 2.0 then people will move on to it and on their own schedule. You could also leave back-porting a fix to 1.6.x for the community. Point out where and how the fix was done in 2.0 and leave the back-porting up for grabs.

I'm certain that everyone is enjoying the renewed activity in HtmlAgilityPack (I know I am) and appreciates your stepping up to the bold task of breathing new life into the project. This issue is just bringing to light that going against semantic versioning may be hurting.

JonathanMagnan commented 7 years ago

Thank you for your feedback from both of you,

I will for sure take some time during the weekend to think about which position I prefer to take.

Best Regards,

Jonathan

JonathanMagnan commented 7 years ago

Looking at the semantic versioning that you provided,

Here is what I believe I currently do:

I combine the semantic versioning from MINOR and PATCH in patch only since they are backward compatible. I also move some fix that is 'MAJOR' to 'MINOR' instead.

Obviously, if we look at this issue: https://github.com/atifaziz/Fizzler/issues/56, by removing a method, the library has introduced a breaking change which I would not have allowed on my side (I always try to be as much backward compatible as possible). Using the semantic, it should have been a MAJOR change, but it should also be a change that should not have happened.

One problem of the semantic versioning provided is it seems to miss something when you want to release a whole new version of the library or introduce a lot of very big changes like whole new features.

You want people to be able to easily notice there is something big that has been done.

It's like behind in beta 0.x, you may introduce some breaking API but you will stay in beta 0.y since you don't want to increment the major version yet.

The major version as described in the semantic versioning work very well for big product like Bootstrap, Entity Framework, Etc, since they take years and years before releasing and can be in beta for more than one year. So their API have time to be well tested (Bootstrap 4 under development since 2014 and BETA has been released a few months ago). However, it doesn't seem to work as well for rapid development project since we cannot distinct MAJOR version from MAJOR version...

Here is my only concern with this semantic versioning currently, how MAJOR version work

Best Regards,

Jonathan

JonathanMagnan commented 7 years ago

Here is an example to better show the problem I try to describe with the semantic versioning for MAJOR version.

Let say the version 2.x is released (The whole library revamp).

So we have now two SUPPORTED version (I cannot stop to support the version 1.x whenever I want...)

If I introduce a backward incompible change in the API to the v2.x, it's simple, we are now in the v3.x!

But if I need to fix something or add value to the v1.x and introduce a backward incompatible change, how to I increment the MAJOR change? I cannot, I must stay in the v1.x ...

That's what I mean when I say using this semantic, we cannot distinct MAJOR version from MAJOR version and which bring this kind of problem.

Best Regards,

Jonathan

atifaziz commented 7 years ago

I'm not sure this is the right forum for discussing, understanding and doubting semantic versioning itself. That would be https://github.com/mojombo/semver/issues and then the conclusions can be posted here.

JonathanMagnan commented 7 years ago

Hello @atifaziz ,

Here is the issue I have opened: https://github.com/mojombo/semver/issues/395

Unless someone provides me a good answer that works and make sense, I will continue to use my own semantic versioning since I cannot use the one proposed because of the MAJOR version problem I have raised.

Best Regards,

Jonathan

craigfowler commented 7 years ago

I know this isn't a democracy but I'd like to vote (even after this has been closed) that proper semantic versioning is followed. HAP is a mature library and a lot of developers depend upon it. People are going to VERY quickly lose faith in it if versions are released to NuGet that don't follow the version numbering conventions which have been accepted by the community.

The meanings of Major, Minor and Patch are very clearly defined by semantic versioning.

Rushing to version 30.x is not an inherently bad thing (look at Google Chome's version history) and it just means that you have made many releases which include breaking changes. On the other hand releasing software which should be version 30 under the name 1.6.0 is really bad, because developers are going to stop trusting you. The result either that is nobody ever upgrades because "every patch seems to break something" or they start looking elsewhere for an alternative HTML library.

JonathanMagnan commented 7 years ago

Hello @craigfowler ,

Thank you for your feedback.

I have hard time to answer to your message (Wrote and erased a lot of time!) since I don't want to start another argumentation about it but I have read your opinion and have take note of it.

Best Regards,

Jonathan