What exactly do release tags mean for packages like `swift-markdown`, `swift-syntax`, etc?

Evolution Discussion
1

presumably because it is part of the DocC stack, packages like swift-markdown and swift-syntax have a really strange versioning scheme.

they apparently have:

  • normal releases (e.g., swift-5.6.2-RELEASE), which use a semver that follows the swift toochain
  • nightly releases (e.g., swift-DEVELOPMENT-SNAPSHOT-2022-06-20-a), which use a calendar date-based versioning scheme, and follows the swift toolchain
  • numbered releases (e.g. 0.1.0) which resemble the normal semvers used by other ecosystem packages (like swift-atomics), but contradict the swift toolchain-based semvers, which are counting from 5.6, 5.7, etc.

what exactly is the “timeline” for how a package like swift-markdown evolves over time, for the purposes of API documentation?

here is one possible ordering:

$ git tag --sort version:refname
0.1.0
swift-5.6-DEVELOPMENT-SNAPSHOT-2022-01-09-a
swift-5.6-DEVELOPMENT-SNAPSHOT-2022-01-11-a
swift-5.6-DEVELOPMENT-SNAPSHOT-2022-02-07-a
swift-5.6-DEVELOPMENT-SNAPSHOT-2022-02-09-a
swift-5.6-DEVELOPMENT-SNAPSHOT-2022-02-10-a
swift-5.6-DEVELOPMENT-SNAPSHOT-2022-02-11-a
swift-5.6-DEVELOPMENT-SNAPSHOT-2022-03-02-a
swift-5.6-RELEASE
swift-5.6.1-RELEASE
swift-5.6.2-RELEASE
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-04-12-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-04-17-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-04-18-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-04-19-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-04-22-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-04-25-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-05-04-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-05-10-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-05-15-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-05-17-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-05-18-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-06-04-a
swift-5.7-DEVELOPMENT-SNAPSHOT-2022-06-13-a
swift-DEVELOPMENT-SNAPSHOT-2021-11-02-a
swift-DEVELOPMENT-SNAPSHOT-2021-11-10-a
swift-DEVELOPMENT-SNAPSHOT-2021-11-11-a
swift-DEVELOPMENT-SNAPSHOT-2021-11-12-a
swift-DEVELOPMENT-SNAPSHOT-2021-11-15-a
swift-DEVELOPMENT-SNAPSHOT-2021-11-19-a
swift-DEVELOPMENT-SNAPSHOT-2021-11-20-a
swift-DEVELOPMENT-SNAPSHOT-2021-12-02-a
swift-DEVELOPMENT-SNAPSHOT-2021-12-04-a
swift-DEVELOPMENT-SNAPSHOT-2021-12-06-a
swift-DEVELOPMENT-SNAPSHOT-2021-12-23-a
swift-DEVELOPMENT-SNAPSHOT-2022-01-06-a
swift-DEVELOPMENT-SNAPSHOT-2022-01-09-a
swift-DEVELOPMENT-SNAPSHOT-2022-02-03-a
swift-DEVELOPMENT-SNAPSHOT-2022-02-21-a
swift-DEVELOPMENT-SNAPSHOT-2022-02-22-a
swift-DEVELOPMENT-SNAPSHOT-2022-02-25-a
swift-DEVELOPMENT-SNAPSHOT-2022-03-09-a
swift-DEVELOPMENT-SNAPSHOT-2022-03-13-a
swift-DEVELOPMENT-SNAPSHOT-2022-03-22-a
swift-DEVELOPMENT-SNAPSHOT-2022-03-30-a
swift-DEVELOPMENT-SNAPSHOT-2022-03-31-a
swift-DEVELOPMENT-SNAPSHOT-2022-04-04-a
swift-DEVELOPMENT-SNAPSHOT-2022-04-20-a
swift-DEVELOPMENT-SNAPSHOT-2022-04-21-a
swift-DEVELOPMENT-SNAPSHOT-2022-04-23-a
swift-DEVELOPMENT-SNAPSHOT-2022-04-24-a
swift-DEVELOPMENT-SNAPSHOT-2022-05-04-a
swift-DEVELOPMENT-SNAPSHOT-2022-05-11-a
swift-DEVELOPMENT-SNAPSHOT-2022-05-18-a
swift-DEVELOPMENT-SNAPSHOT-2022-05-23-a
swift-DEVELOPMENT-SNAPSHOT-2022-05-27-a
swift-DEVELOPMENT-SNAPSHOT-2022-05-31-a
swift-DEVELOPMENT-SNAPSHOT-2022-06-02-a
swift-DEVELOPMENT-SNAPSHOT-2022-06-07-a
swift-DEVELOPMENT-SNAPSHOT-2022-06-08-a
swift-DEVELOPMENT-SNAPSHOT-2022-06-13-a
swift-DEVELOPMENT-SNAPSHOT-2022-06-16-a
swift-DEVELOPMENT-SNAPSHOT-2022-06-20-a

but it’s not clear to me if this is the most logical ordering. nightlies from June 2022 should not be appearing before nightlies from Nov 2021…

2

The dev snapshots can either be "nightly" (from main and no version prefix) or based of a version tag (5.7). The ordering from git is wrong in terms of date because you're sorting by tag name, if you want to sort by creation date do git tag --sort creatordate.

3

The swift‐ prefixed tags are for toolchain builds. All tags in the toolchain must correspond with each other. This is the version of the whole toolchain, not of the individual package.

The simple semantic versions such as 0.1.0 are for direct use a package dependency, these are semantic versions of the package alone.

Presumably you only care about the latter, as swift-markdown is not designed to be arbitrarily linkable from the toolchain.

4

swift-markdown hasn’t gotten a semantic release since october 2021, and there have been a number of toolchain tags released since then, including the (march 2022-ish) version currently being served by swiftinit.org. so if i were to limit the site to semantic versions only, that would actually make the docs regress in time.

5

Is the documentation you are referring to intended for developers or clients? I am not sure anything but main would be useful to the former, and the latter cannot use it at the state you have documented unless they fork it and create their own tag.

You could pester whoever is in charge of swift-markdown to release an updated semantic version. Some of the Swift component packages do a good job of keeping them up to date, others do reasonably if supplied with consistent reminders, and still others do not care if things become impossibly stale and direct you instead to the fork‐and‐tag strategy. Most of the people working on them are only thinking about toolchain use.

6

it is intended for clients. however, if i created my own tags, they would not be meaningful to others, since those tags would only exist in my fork of the repository.

7

And a sea of forks with varying tags is not great either, because it leads to identity clashes. Unless the package itself takes responsibility and becomes more diligent about tagging releases, there is no good answer.

1 Like