search

alyssaxuu / flowy

The minimal javascript library to create flowcharts ✨
MIT License
11.47k stars 998 forks source link

Use a versioning scheme to keep track of changes #108

Open juanmalunatic opened 4 years ago

juanmalunatic commented 4 years ago

I stumbled upon the possibility of using Flowy via npm. However, @joelvh's library was last updated 6 months ago and if we look at the most recent commits of this repo we can see a regular stream of bug fixes and improvements. I found the same issue when checking NgFlowy, a TypeScript port of the library: it works fine, but it is a fork of an older, unnamed version.

I'm aware that one can reconstruct the fork's history based on the commits' dates, but I think that a versioning scheme would make it easier to contribute to third party projects and keep them up-to-date / in-sync with the main library.

alyssaxuu commented 4 years ago

I stumbled upon the possibility of using Flowy via npm. However, @joelvh's library was last updated 6 months ago and if we look at the most recent commits of this repo we can see a regular stream of bug fixes and improvements. I found the same issue when checking NgFlowy, a TypeScript port of the library: it works fine, but it is a fork of an older, unnamed version.

I'm aware that one can reconstruct the fork's history based on the commits' dates, but I think that a versioning scheme would make it easier to contribute to third party projects and keep them up-to-date / in-sync with the main library.

That is indeed a problem. Originally I simply wanted to keep the library without changes until the planned milestone (rewrite of the library with many new features) was released. It's just been taking way longer than expected as I don't have much time anymore to work on Flowy, so instead I reverted to pushing small changes / bug fixes / optimizations from now and then.

I'd like to know if there is a way you'd like to approach that? Maybe having the version number in the README to know whether your version is up to date? Or is there some other more proper way to do it, via commits / having a list somewhere? I haven't really done this before myself so I am not sure, would appreciate any suggestions :)

juanmalunatic commented 4 years ago

Thanks for looking into this! I'm not an expert myself but I think the first part of this write-up by Joel Parker may be a good starting point. He recommends using semantic versioning, a.k.a MAJOR.MINOR.PATCH:

Semantic versioning is a simple set of rules and requirements that dictate how version numbers are assigned and incremented.

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes, i.e. breaking changes.

  • MINOR version when you add functionality in a backwards-compatible manner, i.e. non-breaking changes.

  • PATCH version when you make backwards-compatible bug fixes.

From skimming Flowy's commit history:

As you've probably noticed, semver may introduce too much overhead ... so a date based versioning may be enough?

Whatever the versioning scheme you end up choosing, I suggest that you make use of GitHub's "Releases". This will allow referring to specific, unchanging, versions of the library over time :)

joelvh commented 4 years ago

Those are great suggestions by @juanmalunatic - ultimately, you can choose how to increase version numbers however you like. The simplest way to start is to use GitHub Releases that will mark versions with the code commits in git. Ideally, the code also has the version in a package.json file and gets published to NPM, but I don't know if you have renewed interest in that now @alyssaxuu. Didn't seem to be the case when I was aiming to help with that previously.