Versioning

[toasted-nutbread]

In an effort to make it easier to use or debug specific versions of Yomichan, would it be possible to start adding git tags to commits which correspond to releases? I'm not sure how exactly the testing releases and the stable releases are done, but there might potentially have to be separate tags for testing vs stable. I've seen that there are commits like 63f3e94, but I don't know if that's exactly the commit for release 2.0.1. My proposal:

• For stable releases, tags could be either 2.0.1 or v2.0.1.
• For testing releases, tags could be something like:
  2.0.1-rc, 2.0.1-testing, 2.0.1-dev,
  v2.0.1-rc, v2.0.1-testing, v2.0.1-dev, etc.

We could also start doing multiple testing release candidates for each stable releases, i.e. v2.0.1-rc1, v2.0.1-rc2, etc., which may make things like d8935b6 less of an issue.

Adding these tags would also enable us to use the https://github.com/FooSoft/yomichan/releases Github feature, which could be used as a place to track what the released versions have been. Change notes and/or release binaries could be placed there also if we ever want to do that (that could be managed by the active devs).

[FooSoft]

Yes, this is definitely a good idea. I think we should also come up with something better for version numbers; it's totally arbitrary at this point. Any thoughts on just using dates, Ubuntu style?

[toasted-nutbread]

I think dates as version numbers might be confusing, especially with users seeing the version number jump from A.B.C format to XXXX-YY-ZZ format. I don't know if that would cause issues with auto-updating either; presumably not since the numbers are bigger, but ¯\(ツ)/¯. Shorter numbers may implicitly tell users "how much" the features have changed, whereas dates are really just telling us the time it changed. Dates are also already listed in the addons page for when they were last updated on the extension store, at least on Firefox.

A quick look at several extensions on the Google and Firefox extension stores shows that most extensions use A.B[.C][.D][-extra] format, with [.D] and [-extra] being less frequent. Needless to say, the versioning schemes here also don't follow any standard. This is by no means an exhaustive check.

Like you said, in the end it's completely arbitrary; even something like semver wouldn't intrinsically be meaningful since Yomichan isn't really an API for other software to use. I would be fine with staying with what is currently in place; treating the move from 1.x to 2.x could be a nice place to start tracking. Using the A.B.C format, the numbers could possibly represent:

• A: Major milestone or revision, likely due to a large number of added features or changes. Wouldn't have to happen frequently.
• B: New features, changes, fixes.
• C: Mostly bug fixes and refactoring

(All numbers could go above 9 without incrementing the preceding number.)

[siikamiika]

I don't have a strong preference for the versioning scheme, both date based and semi-semantic versioning can be useful in different scenarios.

I haven't used git tags before, but I was even thinking that the releases could have the git commit hash embedded and they could show it when outputting error logs. I guess this would depend a bit on the current release tooling.

[siikamiika]

My views about the pros and cons of each versioning scheme:

Ubuntu-like:

• + Version is generated automatically and simply
• + Easy to see how old your version is
• - Hard to see how much has changed between two versions
• - We might want to have more than one release per month

Semi-semantic:

• + Version indicates the amount of changes
• + Allows indicating difference at a more granular level
• - Sometimes it's not obvious which version level to increment
• - We are not an API that has to indicate incompatibility unless you take MeCab into account

I have a proposal for fixing each of the cons.

For the Ubuntu-like versioning scheme, we could use it at day level resolution, and add a sequence number at the end that is incremented for each release.

For semi-semantic versioning, we could repurpose the levels so that the third number is a testing release, the second as a stable release, and the first as a major milestone. To enforce it, we could create a release tool that does all these things and modifies some file. It could handle tagging and possibly also commit hash embedding.

[siikamiika]

One con about my proposal that I can think of is if we want to release a hotfix to a stable build, there's nothing obvious to increment except the testing number.

[FooSoft]

My main concern is that it can be difficult to consistently compute the next version number. In a perfect world, I would love semantic versioning to work, but I see several challenges...

What exactly is a feature? Does it have sub-features? Were they added atomically or in sequence? Do you perhaps fix some broken code as a result of refactoring? What would you increment then? I think it could be made to work, but I think it would require that every single commit changes the version number, otherwise it will require a lot of book-keeping to figure out all of the big and small things that have changed between two given releases... Not sure it would be worth it, considering that most users probably won't even care what version number something is until the code is broken and they are reporting it on GitHub.

What about something like this YY.MM.DD.RR?

If we released something today, it would be: 19.12.12.0. If we realized "oh shit, we just broke everyone, quick release again", we could release 19.12.12.1 and so on. We would miss on being able to tell the user just how many things changed through the version number, but ideally we would have change notes for something like that anyway.

[FooSoft]

The above would also of course be combined with tagging of releases (I should have been doing this for a long time, to be honest). We could then just have a master and testing branch, since it would be trivial to get the code of the latest stable version just from Git history.

[toasted-nutbread]

YY.MM.DD.RR would be fine with me, only a few questions come up:

• Should MM and DD be padded to 2 digits?
• Should RR always be included, or only be included if necessary? I.e. omit if .0, add if something needs to be patched on the same day. Hopefully same day patches should be rare.

If we go the date-base route, I think it might be a good time to start doing that in the beginning of 2020, since it would give a nice number to start with.

[FooSoft]

Should MM and DD be padded to 2 digits?

Probably not, the only time it would matter is if you have the versions in a list and you are trying to sort it alphabetically.

Should RR always be included, or only be included if necessary? I.e. omit if .0, add if something needs to be patched on the same day. Hopefully same day patches should be rare.

Probably, for the sake of consistency; otherwise it would look like the version format is changing from release to release. Agreed that same-day patches are rare, but they've definitely happened a couple of times on this project 😉

Also: probably obvious, but the version should be based on the date of the last commit included, not the date the extension is released/uploaded.

[toasted-nutbread]

Update: I have tagged all existing versions starting from 1.0.0. Github lists them on this page: https://github.com/FooSoft/yomichan/releases.

Something that came up while I was doing this: If we use the scheme YY.MM.DD.RR and we want to do a hotfix on a previous version, how should that be handled? The base version would be the original date, but the hotfix commit(s) would be from the current date, which could be misleading.

Doing a hotfix was considered for #298, but the issue was more complex than a single cherry-pick, so we didn't go that route. However, there could be situations where we are able to do a simple patch if browsers break something and all testing features aren't stable.

[FooSoft]

@toasted-nutbread awesome, thanks for fixing up the release history 👍

Determining version numbers for hotfixes is indeed kind of confusing... hmm, I imagine that we can think of RR as a "redo" of of the release based on the commit of that date. Cherry-picked fixes are outside the "natural progression" of the commit history of the project (master branch), so I do not think we have to consider their dates in determining the version number for the hotfixed release.

[FooSoft]

Wow, Firefox developer hub is annoying. They do not allow versions with four components (ww.xx.yy.zz), so I have to trim the "release" component from them. We might have to just stick to doing YY.MM.DD just because of Mozilla. I have already uploaded a version to Google Play using the four component format, so that will be annoying.

[FooSoft]

...or I guess they just don't like the leading zeroes in the versions. So I guess we will not be doing that going forward.

[toasted-nutbread]

Going to close this for now since it seems like we have a working versioning scheme going forward.