Document what version numbers mean

[Rangi42]

RGBDS version numbers take the form major.minor.patch. The major version has always been 0, and we haven't been strict about what counts as a "major" versus a "patch" release, because we haven't had criteria to be strict about. (Although we've usually adhered to "introduce deprecations and removals in non-patch releases.") Once we reach version 1.0.0, we should set some standards for what subsequent releases will mean.

The obvious candidate that many people have suggested (or already expected) is semantic versioning ("semver"). Major versions are for breaking changes; minor versions are for non-breaking new features; patch versions are for non-breaking bug fixes.

One difficulty with applying semver to RGBDS is that "breakage" is relative. If we add a new FOOBAR() function, any assembly code that uses foobar as a symbol name will need changing. However, we could decide this sort of thing ("what counts as major backwards incompatibility") on a case-by-case basis.

Another versioning alternative is date-based: an October 31st, 2025 release would be versioned 25.10.31. We probably don't want to jump straight to major version 25, but the major version could just start from something else instead, like web browsers whose versions keep ticking up every N months. (E.g. if we release version 1 in 2025, then the first release in 2026 would be 2.mm.dd.)

A less serious but still common approach is "pride versioning". A big release you're proud of gets a major version (even if it's just something like an internal rewrite/optimization or a cool new feature that doesn't break anything); a "normal" release gets a minor one (even if it technically breaks something, like when we removed jp [hl]); and "embarrassing" bugfixes get a patch. This is closest to what we've already been doing in practice.

"RGBDS isn't semver" (and the rejoinder "RGBDS is still 0ver") frequently crop up in Discord discourse, so setting an official versioning policy would hopefully settle those.

[aaaaaa123456789]

Since the main purpose of semantic versioning is to facilitate integration, I'd recommend defining anything that could break an "innocent" codebase (i.e., a codebase that isn't purposely attempting to be broken by an update) as a breaking change.

This would eventually mean determining what identifiers are off-limits for users, indeed — and categorizing anything using those identifiers as a codebase that is purposely attempting to be broken. (The double-underscore rule seems to be in force in practice, for instance.)

I should go ahead and say that warnings are never breaking changes, and that anyone using -Werror on a list of unknown warnings is asking for breakage on update. (This could easily be a feature: some people actively want this kind of breakage. But the point is that it is deliberate.) Changes in warnings shouldn't trigger a major update at all.

[vulcandth]

Once we are at a state where we can stamp 1.0.0 on a particular release, I support semver.. but I don't agree that just because a new function name is created and there being an off chance of a collision with a repo's existing symbol name should warrant considering the update a "major" version update. At that point we might as well not add anything, or we risk bumping the major version with nearly every non-bugfix update. Yes, if we know the name we are picking is in active use out there, then that particular case can be re-considered.

Either way, I recommend semver, and then writing up expectations on what is considered "breakage". As-in, for example, you might state a minor update "should not expect breakage", but that doesn't mean it won't ever inadvertently cause it.

[VariantXYZ]

Just to chime in, I think semver makes sense. Currently, it seems like the current 'minor' version specifier is effectively a breaking change that's required changes due to deprecation or outright syntax changes.

In any projects I use with rgbds, I specify the required version as '0.M.x' (e.g., 0.7.x with no guarantees it will still work for 0.8.0 and above or 0.6.0 and below), with the assumption that rgbds 'patch' versions shouldn't change anything or add new functionality. I'm not sure how true this is, but the alternative is just specifying exact versions. All my docker images just checkout specific revisions or tags accordingly.

Changes in warnings shouldn't trigger a major update at all

On the topic of warnings: warnings that call out efficiency/ambiguity are useful and IMO should be treated as non-breaking changes.

However, I think deprecation warnings should be classified separately and planned 2 major versions in advance (avoid printing warnings til the next major revision and then removing things outright in subsequent ones). Code changes for toolchain changes don't strictly need to be integrated without an intentional toolchain version update IMO.

[vulcandth]

 I think deprecation warnings should be classified separately and planned 2 major versions in advance (avoid printing warnings til the next major revision and then removing things outright in subsequent ones).

That is excessive... Waiting for two major versions before doing a "breakage" when the whole point of major updates are for breakages is silly.

Reference the following:

How should I handle deprecating functionality?
Deprecating existing functionality is a normal part of software development and is often required to make forward progress. When you deprecate part of your public API, you should do two things: (1) update your documentation to let users know about the change, (2) issue a new minor release with the deprecation in place. Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API.

Source: https://semver.org/#how-should-i-handle-deprecating-functionality

[VariantXYZ]

Sure, a minor version stagger is fine too. The scenario I wanted to avoid was saying "this codebase is completed will compile fine on this version base" and then having issues for deprecation warnings crop up later when someone tries to build it. If there are legitimate code issues caught, I would like to catch those types of warnings... but of course, getting those warnings backported to a patch in an older revision is a luxury I can wish for but understand might not be granted.

As long as there's a consistent version specifier to possibly catch useful warnings and ignore deprecation, that's good enough for me.

[vulcandth]

I would argue that deprecation warnings are useful. And they are just warnings... They won't prevent building.. you can't expect them not to be able to deprecate things. ...Or you can lock into a minor version.

[VariantXYZ]

Or you can lock into a minor version.

Totally reasonable.

I would argue that deprecation warnings are useful

Poor choice of words on my part. I think they are useful. To clarify: I just felt like toolchain-related deprecations belong in a different class than code warnings and the distinction is helpful within versioning.

I guess, as a similar question: would introducing warnings that help identify bugs/improvements be OK within a patch version in semver?

[Rangi42]

When we switch to semver it'll probably be a good idea to make a SEMVER.md FAQ-style file clarifying these points for the maintainers (like RELEASE.md).