search

jplayer / jPlayer

jPlayer : HTML5 Audio & Video for jQuery
http://jplayer.org/
Other
4.6k stars 1.47k forks source link

Add a changelog #262

Closed slavafomin closed 9 years ago

slavafomin commented 9 years ago

As far as jPlayer is not really consistent with SemVer standard I think it will be a good idea to introduce a changelog.md file with the list of changes introduced in new versions. This will really help with migration. I will lock my project to the current version of jPlayer and will update it manually. Changelog will help a lot. Or at least we can use migration.md file with the list of changes that break compatibility.

Thanks!

thepag commented 9 years ago

I am happy to add the 2 files. For now the changelog would list changes from 2.8.0. I'm not sure if/when the other log of changes would be added.

I currently maintain a log on the website: release notes

I'll also take a look at this SemVer standard to see where we can improve.

slavafomin commented 9 years ago

Thanks!

The idea behind SemVer is pretty simple actually. The version string consists of three parts: MAJOR.MINOR.PATCH.

  1. You increase the PATCH version when you fix some issues in the code.
  2. You increase the MINOR version when you add some new features to the code.
  3. And finally, you increase the MAJOR version when you add some compatibility-breaking changes.

In case of jPlayer it fails to increase the MAJOR part when necessary - that's where the problems arise.

thepag commented 9 years ago

Aha... So you want us to make a MAJOR version increment just because the repository structure changed?

jPlayer only had a few minor tweak - PATCH - changes and then included the new features when I incremented the MINOR version in 2.8.0. The changes to the repository were to make all the files available in one place and to make it easy for novices to download the repo and for it to work without installing any 3rd party apps, like node or bower.

I'll not comment any more on this before I get round to reading the doc.

thepag commented 9 years ago

Plus, we actually already follow those rules... http://jplayer.org/download/

The difference being, my point of view is when jPlayer changes... Your point of view is when the NPM package changes. jPlayer remains backward compatible, it is the package that has changed in structure.

thepag commented 9 years ago

The main topic of this issue has been addressed and pushed to the v2.8 branch.

slavafomin commented 9 years ago

If you are separating this things (i.e. version of the jPlayer plugin and version of the GitHub repository) then GitHub repository should have a versioning system compatible with SemVer, because Bower and npm are using the version string to update dependencies.

In my case, my project was broken after a minor routine dependency update procedure (and it shouldn't really happen) because:

  1. file structure of the jPlayer repository was changed
  2. the template and styles were also changed, so we have to replace template in our project, change JavaScript and CSS
thepag commented 9 years ago

Thanks again @slavafomin for explaining.

I will talk with @maboa tomorrow about raising the major version to 3. To me it is just another number, but someone might think it is a groundbreaking new release of jPlayer.

I have this nagging feeling that I've already broken bower for the 2.x series and I will not have the time to fix that retroactively. It would be rather complicated and I doubt my git skills are up to it. Also, increasing the major version now is already too late, except that it might be more obvious how I messed up to veterans like yourself. NPM should actually be fine, because I never published it before 2.8.0, but I suppose people may have npm installed direct from the jplayer git repo - so ok, I messed that up too.

Plus... This changelog is going to double my release notes writeup. Think I'll have to dump the webpage and then point to the changelog... Not sure what I'll do there actually. Maybe link between the old and new for the time being. Just trying to keep DRY.

slavafomin commented 9 years ago

Just a thought to keep changelog DRY:

You can create a changelog in Markdown format in this repository and move all changelog details in it from your web page. Then you can edit this file when you introduce any changes.

On your webpage you can actually load this changelog.md, parse it and convert to HTML in order to embed it to your page. You can do it serverside or client-side using AJAX. The following JavaScript library actually can be used to convert MD into HTML: https://github.com/evilstreak/markdown-js.