Libraries Version Scheme

[tajmone]

EDITED (2021/11/30): see the new VERSIONING.adoc document.

---

@thoni56, I was thinking that for the various StartLib implementations we should adopt Semantic Versioning 2.0.0 as the versioning scheme standard.

This mean that end users would be able to look at any latest library version number and immediately deduce whether they use it in their adventures without having to tweak their code.

But this would also mean that we'll be seeing quite a lot of MAJOR version bumps in the initial stages, for many of the pending changes to integrate new ALAN feature would introduce breaking changes — e.g. dropping the worn entity in favour of a worn attribute, since we've seen the problems it can cause, and various other changes in the library like filenames, etc.

I'm not sure whether that's a problem or not, but I noticed that many people who aren't used to SemVer find it puzzling that a library bumps-up its MAJOR version due to a single backward breaking change — yet, it's such a useful convention! For this reason, SemVer is so often misused (even on GitHub), where many authors believe that MAJOR version bumps should only be associate with major code rewrites or ton of new features.

The summary description of SemVer 2.0:

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

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards compatible manner, and
3. PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Obviously, the extra segment for pre-release and metadata labels would only really be used in development branches, when collaborative editing is at play.

I personally find this scheme so intuitive and practical, especially for our libraries.

But if we adopt the SemVer scheme, we need to ensure that contributors adhere to it.

Versioning Multiple Libraries

Another issue related to version numbers is whether the different language implementation of the library should somehow be kept in synch in this respect, or if each library follows and independent version.

We'd naturally hope that improvements in the English library would also be replayed on other languages, but we don't really have any guarantees in this respect, for that depends on whoever is maintaining the port to a specific locale — i.e. developers who master that target language —, but these might not always be actively maintaining their ported work (the Spanish library was resumed from the web, so we don't even have a maintainer for it right now).

Personally, I think that every library (i.e. locale port) should have its independent version scheme, and that it doesn't matter if the English lib has reached v5.x.x and the Spanish is still v1.x.x, regardless of which features were added/updated in each — e.g. on library might introduce multiple breaking changes at once, hence bumping a single MAJOR version number, whereas another library might add these changes one at the time, resulting in multiple MAJOR bumps for the same changeset of features.

Starting Point

In any case, once we reach and agreement on the versioning scheme, I would like to proceed with setting the English and Spanish libraries to v1.0.0 (or whatever scheme), since I think that their first release should match their upstream unchanged code. After that, we can start changing them and bumping up their version number.

That's mostly because it simplifies tracking changes in their ChangeLog, since that's a strict requirement of the Artistic License 2.0.

ChangeLogs and Artistic License

I was thinking that since we've renamed the libraries, we could refer to their original Lib v0.6 upstream version for their older ChangeLogs (i.e. linking to their archived version on the ALAN Goodies project, to which I've recently also added an archive copy of the original Spanish pALANte library).

This would allow us to keep the ChangeLogs in this project shorter and more consistent, and I believe that since the libraries here are new derivate works, this is in compliance with the Artistic License, especially since our org also maintains their archived copies, with ChangeLogs and all.

But I wanted to ear your opinion on this, since you've been using this license much longer than I have. We surely don't won't to handle licensing wrongly here.

[thoni56]

Actually, I'm no expert on licensing, I have just adopted what seems as a reasonable one given my very limited understanding, so I might not give "expert advice" on that.

But I do tend to like SemVer in principle, although I haven't (probably) been rigorous in using it. But I agree that following that is a good thing and would help users a lot.

I agree with using 0.6 in the Goodies project as a stepping stone is a good idea and make some things much easier, so let's do that.

When it comes to having the libraries in sync, again, I agree with your sentiment that this is not required, and might be prohibitive as it would imply that a library maintainer was forced to follow the English library, which is more of a wish than a rule. Also all features in the English library might not be easy to port and vice versa, so it's better to have some leeway/freedom here.

Wrt. many MAJOR updates in early develpment, maybe we can adopt a tiny tweak to the AL2.0 by saying that as long as we're in the 0.x.y there might be MAJOR incompatibilities between versions. Then we have the option to decide when 1.0.0 is released and becomes the real "MAJOR" version baseline.

This of course opens up the question about what we'd consider 1.0.0. And I think there are at least a few things that we want in that (although I'm not sure they'd considered to be MAJOR incompatibilities):

• using parameters to enrich messages instead of "You can't do that to that." style
• decide and implement $<n> or Say(On Using '$<n>' vs 'SAY' Constructs #15)

Thinking about it we should probably define what MAJOR and MINOR incompatibilities actually mean in the libraries. A small change in a message might make all your tests fail, is that allowed for a PATCH or does it force a MINOR, or even MAJOR version update?Obviously not a MAJOR, but anyway.

Building on that here's a first attempt to get that discussion rolling:

• MAJOR: makes some games crash, non-compilable or similar, unless source is changed
• MINOR: changes flow of events, outcome of some actions, games can be compiled without change, but solutions might need updating
• PATCH: changes in text which might not be exactly the same as the version before but nothing in the game play is altered except text output

This is just an initial, of the top of my head, list. There are probably other types of changes that should go into this list. Primarily we should consider what impact to a game author it might have, as I've done above, but, we should also think about how frequent various types of changes might be, so that that type ends up in a reasonable change level. E.g. if text output changes would force a MAJOR update then we'd soon be in three digit major versions... ;-)

[tajmone]

As far as the Artistic License clause that changes must be listed, it's really a directive for derivative works from the original. In our case, the Library 0.6 has always been part of the ALAN project, so keeping a detailed ChangeLog is more of a good practice formality than a license requirement. The same applies to ports of the library to other languages, for they are indeed derivative work from the original codebase (these, being by third parties, must provide a list of changes).

But then, again, we're dealing with a rather fuzzy concept here: How detailed does the changes list need to be? It could be a list of every feature, or something short like "translated from" or "entirely reworked". It's hard to say, so common sense should be the guide in these decisions.

My understanding is that by renaming the library we've created a "new product", so linking to the upstream ChangeLog for previous changes (not done by us, anyway) should be more than enough. These "list changes" clauses are usually intended to avoid confusion between the original code and derivative works, so the name change is significant here. Also terms like "us/our" and "them/their" have a very vague meaning in these libraries, since they were created by members of the same community, and because their license is always that of the ALAN codebase (i.e. the Artistic License with your preface on top).

As for the SemVer scheme, I share your same concerns. SemVer was designed for code APIs, and it doesn't always play well for applications, especially GUI apps, where it's unclear what a breaking change means.

For our use case, I would focus mainly on delivering clear and concise information to end users of the libraries (i.e. authors) so that they might have a good idea of what to expect when attaching a new release to their adventures.

Building on that here's a first attempt to get that discussion rolling:

I entirely agree on the definition of MAJOR changes, i.e. something that requires tweaking an existing adventure in order to switch to the new MAJOR version of the library.

MINOR changes are trickier though. There's no doubt that these include:

• New features available (by optionally editing the adventure).

As for:

• MINOR: changes flow of events, outcome of some actions, games can be compiled without change, but solutions might need updating

you're probably right. If we were to count as MAJOR bump any tweak to a VERB or its SYNTAX, then we'd soon end up with v9999.0.0 (which is ridiculous). So, probably as long as it doesn't guarantee compiling failure, and consists of some editing to pre-existing features, it might be enough to mention potentially breaking changes in the ChangeLog and release notice text.

What makes this even more entangled is the fact that new ALAN version are at stake too. E.g. let's say that a new release of the StartLib begins using the new UTF-8 sources feature of ALAN Beta8. Of course, this is a breaking change, but only if you're still using older versions of ALAN, but not because of the library itself. Since each library is associated to a specific minimum ALAN release (i.e. the latest available when the library version was released), we should only consider changes from the library code, and assume that these will be applied to the latest ALAN version when a user tries to recompile his/her adventure using the new library.

I'm sure we'll eventually find a reasonable balance here.

by saying that as long as we're in the 0.x.y there might be MAJOR incompatibilities between versions. Then we have the option to decide when 1.0.0 is released and becomes the real "MAJOR" version baseline.

That's a very good strategy, and indeed one in full compliance with the SemVer specification. The 0.x.y version is usually for Beta and Alpha work, but we could start from this, since there are so many big changes ahead in the next six months — switching to UTF-8, dropping the worn entity in favour of an attribute (indeed a MAJOR change), and probably reorganizing all the library modules, how verbs are distributed, and many other changes that could benefit from the StdLib experience developed by @AnssiR66 in the course of time, which we could apply to the StartLib to make it more efficient, but without bloating it.

I'll definitely be using 0.1.0 as the baseline version for the current libraries, indicating identical code to their upstream counterparts. This will give us freedom into bumping the MINOR and PATCH numbers as much as we like, treating MINOR as if it covered both MAJOR and MINOR, and PATCH having the usual meaning. By the time we reach 1.0.0, we should have a better vision of where we're heading, and how to plan packing all breaking changes into a single MAJOR bump by using dev branches and release candidates — there'll never be urgency for releases, we might just keep developing RCs in dev branches until ready, even if it means updating official libraries less often; and users can always use release candidate and dev versions, at their own risk.

[tajmone]

StartLib EN v0.1.0

@thoni56, I've finally managed to clean up the English library sources and docs and create the initial Beta v0.1.0, ad discussed.

I've updated the CHANGELOG, making it clear that we'll be only tracking changes since the Lib 0.6.2 (as archived on ALAN Goodies).

I've renamed the main module std.i to StarLib.i, to avoid confusion with the previous library.

I've also updated the CONTRIBUTING doc, providing some guidelines for porters of the library to new languages. I've suggested some conventions that seem to make sense to me, but which are (of course) open to suggestions and changes. These include naming the main library module StarLib.i, regardless of the locale (to facilitate individuating it to maintainers).

Italian Library WIP News

My work on the Italian port is going ahead, and I'm sharing it on the dev-alan_it (which I'm constantly rebasing). I won't include it in main branch until it reaches v0.1.0, to avoid confusion.

[tajmone]

StartLib ES v0.1.0

@thoni56, I've now also cleaned up the Spanish library sources and docs and create the initial Beta v0.1.0, as discussed.

All changes mirror those of the English v0.1.0, so we have a consistent baseline for all the legacy libraries that were imported into the project.

I've been reading through the Spanish Lib sources, and noticed a few things that might benefit from improvements in terms of code, and others that don't quite convince me.

I should be able to handle code updates that don't involve touching generated text, but we'll eventually need to either contact Bruce Humphrey and see if he's willing to take on its maintenance (11 years have past!) or else make an announcement in the various IF groups (especially the Spanish ones) to see if any native speaker comes forward for the task.

My problem is that I can read and understand Spanish, but have no clue whatsoever on how to write it, spell it, etc. My knowledge of the language has no academic grounds, just my personal experience from having lived in Spain for a while. So, there are obvious limits to my contributions to the Spanish library code base.

[tajmone]

Contacting Bruce Humphrey

As a first attempt to contact Bruce Humphrey, I've published a comment in his blog to inform him that we've republished his pALANte library, and to let him know that we'd be delighted to have him on board.

The blog hasn't been updated since May 2010, but since his account is still active let's hope he sees the comment I just left.

My next step will be to join the Spanish IF forums, and let them know that ALAN Spanish is alive again.

[tajmone]

Versioning Doc Updated

I've dropped the old VERSION_SCHEME.md in favour of the new VERSIONING.adoc document.

This is an heavily updated version of the article explaining how the library version scheme works, now providing practical examples to simplify understanding how library version numbers should be interpreted in terms of how they can affect existing adventures.

I've also added more text, digging deeper into how SemVer works, and improved the pre-existing text.

I've switched to the AsciiDoc format since this article will ultimately be included in the distribution package in HTML format — possibly as part of a larger document that ships with the libraries.

Unfortunately, the way GtiHub renders the AsciiDoc preview is fairly poor, it lacks basic styling for the core AsciiDoc elements (example blocks, admonitions, etc.) and those that are styled are poorly styled too (misaligned contents in grid-based layouts, etc.).

I never quite understood why GitHub has invested so little energy in optimizing the CSS for previewing AsciiDoc documents. That's rather unfortunate, especially since GitLab has greatly improved AsciiDoc rendering in the course of time.

Anyhow, I hope that the new updated article is clearer for authors who are new to SenVer, and to version schemes in general. I've opted for a shorter file name too, since VERSION_SCHEME.md was too verbose, especially considered that the final document in the package will have an entirely different name (if not included in the README.html), so for us maintainers the shorter VERSIONING filename is more than sufficient (there are no other version schemes at stake here).