Dialog version naming

Dialog currently has three different version numbers:

  • The software version: 0m/03
  • The library version 0.46
  • The manual version: 31

At first, it feels like we only need the software version. However, new versions of all three are delivered as a unit, currently.

I think it is worthwhile to make a distinction between the software version and the library version, as it is common to hold onto a copy of the library even when upgrading the tools (my Sanddancer project does this currently).

I’m not sure what the value of the manual version is, given that we are looking to tighten the relationship between releases (the software version) and the manual.

1 Like

Reviewing Stefan’s release notes, the 0m part increments only when the software (dgdebug, dialogc) changes; the 03 part increments when the library version changes; in most historic releases, the tools were unchanged and the release was just to distribute the new library.

1 Like

There’s been a bit of discussion here. Personally, I think we should have the compiler, library, and manual all use major/minor/patch versioning; the compiler can continue to write the minor version as a letter (that’s needed to embed it into the Z-code file), but the other two should use numbers.

Linus asked that we bump the major versions to 1 for our version, so my vote is to set the compiler version to 1a01 and the library and documentation versions to 1.0.0, and go from there. I think it makes sense to have the documentation have its own versioning, because it needs to be updated whenever either the compiler or the library is changed.

2 Likes

The easiest thing for Antora is to have a naming pattern for branches that correspond to releases, so branch maint/1a01 would be created after 1a01 is released, and the manual repo will find that branch and add it as one of the versions.

With Antora, you will mark the version in main as unstable, so the default when landing on the page is the most recent stable version. Lots of this goes into the manual/antora.yml file, which will be different in each branch.

Once we get things firmed up, I’ll write instructions and/or scripts to make sure this is right.

3 Likes

We can use tags rather than branches, but there are some drawbacks to doing so: Content Source Versioning Methods :: Antora Docs

I think there needs to be a bit more noodling on this, but no dire rush.

1 Like

I weighed in on the other thread, but my take is roughly:

  • The version scheme for the compiler is very clear, thanks to Linus: start from 1a, go to 1b when we change the language. Great!
  • Personally I think the simplest move would be to use the same number for the library. I agree not everyone upgrades them together, but I don’t see the harm in having a 1a/03 compiler and a 1a/02 stdlib. IIUC since we need to bump the letter on any language change, all I’d need to check to make sure that my tools and stdlib were compatible would be to compare the but before the slash. And it makes it a bit easier to build release tooling etc. if the number is shared. (Since I’ve been doing the build tooling so far I find this motivating… :sweat_smile:)
  • I don’t see the point of versioning the docs separately… it seems very important that the docs state what version they’re documenting, but adding a third number seems likely to only add confusion. Especially with the docs branch approach suggested above it seems pretty safe to drop.
1 Like

A slightly different proposal, then: separate the versions of language and library, but instead of giving the docs their own version number, attach the language version number to the language docs and the library version number to the library docs? Increment the patch number of the library/language when the docs are updated in a significant way, but otherwise reduce the three version numbers down to two.

1 Like

Referring to the docs by the version numbers of the things they’re documenting sounds like a positive step!

Could you expand a bit on why this bit is useful?

So that we can distinguish between versions of the documentation (“until version 1a04, the documentation incorrectly said that space would be added between punctuation characters when printing; in version 1a05, that was fixed”) even if we don’t update the compiler or library at the same time.

I don’t expect this to happen much, though. We’ve currently got a backlog of issues in the documentation from the last few years, but once those are cleared out, I expect the docs to only be updated when other components are.

In other words, my new proposal is, at our first full release:

  • Set the version number of the compiler and the compiler documentation to 1a/01
  • Update the patch version every release, and the minor version every time the language itself changes (e.g. with my addition of (current div width $))
  • Set the version number of the library and the library documentation to 1.0.0
  • Update the patch version every release, and the minor version every time there’s a change in the functionality (not just bug fixes and optimizations, but adding new public predicates or removing old ones, like (gender-neutral $))
  • Keep the major version as 1 until something truly drastic changes, beyond any of our current issue reports

How do people feel about this? My main reason for wanting to keep the compiler version and library version separate is because we specifically want old libraries to keep working with new compilers (though not vice versa); Miss Gosling is never going to get updated to a 1.* library, but I would like it to still compile with 1.* compilers. Having separate version numbers reinforces that that’s a goal.

1 Like

I’m just trying to figure out what version number we use for the documentation, and when that number changes. “1a” or “1a/01”.

I can definitely see keeping the fore matter: “This is version X of the documentation, for version Y of the library and version Z of the tools.”.

My proposal is to split the documentation version number in two—the compiler documentation uses the compiler version, and the library documentation uses the library version.

In other words, it’s “the documentation for compiler 1a/01” and “the documentation for library 1.0.0”. That way we only have two version numbers to think about, not three.

1 Like

That’s going to be a bit of an uphill challenge; it’s basically one version per content root, and I’m not sure how well I can have a unified nav across two (or three, including the preface) content roots.

Well, the compiler source and the library are stored in the same repository at the moment, and that hasn’t become an issue yet; I don’t think we necessarily need them to be in different content roots. Just different version numbers in the headers.

I would propose this:

  • Antora manual configured to build documentation from the main branch, and from maint/* branches (i.e., maint/1a).
  • The main branch is given the version number latest and is marked as a “prerelease” (in antora.yml)
  • The version number is linked to the major version (‘1a’)
  • As done today, the documentation breaks out the major/minor version of the tools (e.g., 0m/03) and the version of the library (1.0.0).

Cutting a release from main:

  • Update various version numbers in antora.yml
  • Set prerelease to false
  • Update changelog, etc.
  • Commit changes
  • tag the release (e.g., release/1a01, perhaps)
  • If the first release of a major version, create a maint/ branch (eg. maint/1a).
  • Package everything up and:
    • gh release create ...
    • gh release upload ...

Much of the above could be scripted; for example, the version number could be extracted from stdlib.dg and applied to antora.yml, to ensure they are synchronized.

1 Like

I’ve still been struggling with making branches (though I’m getting better!) and I have no idea how gh release works, so I don’t want to take responsibility for doing all this—but that all seems reasonable enough to me.

I’ll take a stab at something along those lines this weekend!

1 Like

What is the benefit of having more than one version number?

From the outside it seems a lot easier if I have version 22 of the compiler I know I need to read version 22 of the documentation and I know that version 22 of the library is the version that it was released with (even if I may, at my own risk presumably, prefer to use some other version of the library).

I sense I’m fighting a losing battle on this one, so if the consensus is that we should stick to a single version number, I can live with that. I just don’t want to give users the impression that, if they’ve extensively revised the library for a particular game, they need to either not update the compiler, or redo all their revisions to the library for each release.

The architecture is currently designed so that you have a single centralized compiler but a separate copy of the library for each game, and separate version numbers seems like the best way to enable that architecture.

1 Like

Many past releases featured only additions to the library. If library version 23 comes out, users may start worrying that they can’t use it with compiler version 22 even if the new library doesn’t use any updated compiler features. The only alternative is to release a version 23 of the compiler which is identical to version 22, which creates an additional maintenance burden.

3 Likes