mirror of
https://github.com/BookStackApp/BookStack.git
synced 2026-02-05 00:29:48 +03:00
Move to Ubuntu based versioning, drop the Beta #2106
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @ssddanbrown on GitHub (Feb 18, 2021).
This is a proposal to move to Ubuntu-style version numbering for feature releases. This issue has been opened to gather feedback or identify potential issues I may have missed.
Version Format
This would utilize a
<2 DIGIT YEAR>.<2 DIGIT MONTH>[.<OPTIONAL PATCH DIGIT>] format.Patch releases would not increment the year/month values, only the last patch patch digit.
Version Examples
Reasoning for Ubuntu Versioning
The Ubuntu versioning system is really great in the respect it makes the relative age of a release instantly identifiable based on numbering. It's fairly common that people will mention their version of BookStack, and I'll have to go through releases or blog posts to identify the age of the release. Having the feature release date in the numbering gives it value while still incrementing over time.
While other methods, such as semver, provide value in explaining compatibility, BookStack is not really designed to be a dependency in systems where this would matter. In addition, having to decide what counts as breaking or not would add friction to releases. I'd consider many feature releases as potentially breaking, in some manner, to a small portion of the user-base, while many other's would not experience a change.
Potential Issues with Ubuntu Versioning
Wanting to deploy two feature releases in a single month may pose an issue if desired. Looking at the past release pace, this would be a fairly large anomaly. We could always cheekily use the following month if majorly important.
Users could possibly get confused, and think they've missed out on versions due to gaps in the numbering.
Dropping the Beta status
I've been keeping the beta flag on releases, even after 5.5 years, more or less as a warning since this is not a full time supported enterprise offering as some may expect. That said I have tried to ensure a stable and supported upgrade path through every version since inception, and I do try to ensure new releases are somewhat stable.
The beta flag has caused friction in some scenarios, where people dismiss the platform assuming it's unstable which is generally not the case.
In this change I would not be altering how I/others work on the project, Nor would I expect the relative level of stability to change. It would just be dropping the "Beta" text in release version names. I think dropping this at the same time as changing the version numbering will help as we'd avoid any kind of "1.0" release where people may assume some change in operation.
As part of this I'd look to add a section in the docs to briefly explain the versioning and to explain the stability/support targeted by the core project in the interest of transparency.
@bridgeyuwa commented on GitHub (Feb 18, 2021):
As long as they follow up with the blog they can get informed about the releases. I think they won't get confused.
@ashleycawley commented on GitHub (Feb 18, 2021):
I think the change in versioning is a good idea, also dropping the beta flag/status.
Ever since I discovered this project a few months back and have been using it on a almost daily basis for personal and work I have been impressed with the stability and how polished it feels.
I can see how new comers may see the status of Beta v0.31 and it could be off-putting to some, making it feel very young or not ready for use perhaps, whereas I think it is quite to the contrary, I think the stability and robustness of it in use shows that it has years of development and progress under its belt, so I know it might sound daft but I also think that the higher the number of version less technical people might appreciate that it has been around a good while irrespective of if they actually understand the versioning scheme!
I would like to thank all the contributors to this project, I think you've done a superb job so far, so thank you.
@ihatemyisp commented on GitHub (Feb 19, 2021):
Having used Bookstack since v0.19, I can honestly say it's been fantastic and nothing but solid.
That said, I support the versioning scheme change. You've laid out solid evidence for it. Also, as @ashleycawley said, it would provide for a "hey, this has been around for a long time, it's got to be at least decent" perception to those that judge a book by it's cover.
Regardless of the final decision, I'm going to continue using Bookstack and not just because I'm too lazy to export/import my pages and pages of information to another application.
Cheers to everyone that's contributed, Bookstack is great, but you knew that.
@cdrfun commented on GitHub (Feb 19, 2021):
The Home Assistant Project did a similar move: Leave Beta and move to YYYY.MM.P Versioning. Personally I like YYYY more than YY, because then it becomes instantly clear this is the year. This would also help to prevent users being confused, as the distinction between new and old version numbering is better.
From a stability perspective, and also feature-wise for me, the project is definitely out of beta.
Just for the APIs a semver versioning would be clearer for everyone developing against them. Maybe it's an option to get a separete API version number which can be queried or has a separate endpoint? But imho this is nothing which should prevent the suggested change.
@ssddanbrown commented on GitHub (Mar 20, 2021):
Thanks for the feedback so far everyone. Looks like we can go ahead with this. One extra disadvantege I've found for this change is that I can't predict the version/name of the next release which makes it difficult to name release milestones and reference in comments here. Might just have to be generic with the names and change them out close to release.
@cdrfun
Thanks for the suggestion, I initially was tempted to use that but after some extra thought I quite like how
YYdoes not exactly mirror a year, to make it more obvious it's a version instead of a random date.That probably won't happen, at least for a good while; It'll just be too much effort to maintain that kind of system. For now it'll just be dependent on your BookStack release version. That said, I will try to keep API stability in mind and I'd look to note any breaking changes in the update notes like all other platform potentially breaking changes.
@djmattyg007 commented on GitHub (Mar 22, 2021):
Another potential idea is to use the scheme JetBrains use for their IDEs:
2021.12021.1.1,2021.1.2, etc2021.2, and so on@ssddanbrown commented on GitHub (Apr 10, 2021):
Since v21.04 has now been released, I'll close this off.
Thanks everyone for your input on this!