Request to Reinstate Semantic Versioning for Clarity and Compatibility

[relatedcode]

Semantic Versioning, often abbreviated as SemVer, is a versioning scheme for software aimed at conveying meaning about the underlying changes with each release. It's structured as MAJOR.MINOR.PATCH, where:

• MAJOR version increases indicate incompatible API changes,
• MINOR version increases add functionality in a backwards-compatible manner,
• PATCH version increases are for backwards-compatible bug fixes.

This system helps developers and users understand the impact of updating to a new version without having to delve deep into the release notes. For instance, increasing the MAJOR version signals that users might need to make significant changes on their end, while a PATCH update suggests minor, typically safe improvements.

https://semver.org

[fumito-ito]

+1

In addition, I request to reinstate semantic version to facilitate referencing from other libraries.

I am referencing this library from a package I am creating, but I cannot use package(url:from:) in Package.swift and am forced to use package(url:revision:).

[twostraws]

I think(?) this same problem is hitting my Ignite project: SPM is complaining that adding Ignite fails because it relies on an unstable package: swift-markdown. I might switch to the solution suggested by @fumito-ito, but actual semver would be most welcome.

[fumito-ito]

Follow-up:

@twostraws

Unfortunately the #178 (comment) solution did not work.

This is because package(url:revision:) cannot be used as a stable version specification, as described in the SPM documentation.

https://github.com/apple/swift-package-manager/blob/4dc41b046381ddb9297127ccc83149994770b28c/Documentation/PackageDescription.md?plain=1#L400-L403

Note that packages which use commit-based dependency requirements can't be added as dependencies to packages that use version-based dependency requirements; you should remove commit-based dependency requirements before publishing a version of your package.

Since I had no choice, I forked apple/swift-markdown to set the release tag. This is not a good solution, but I think it is a practical one that can be taken under the current situation.

https://github.com/fumito-ito/swift-markdown/releases/tag/510.0.0

[Kyle-Ye]

https://forums.swift.org/t/swift-markdown-fatal-error-a-closed-block-directive-container-cannot-accept-further-lines-of-content/68127/5

Maybe we can expect a 0.4.0 release for release/5.10. cc @QuietMisdreavus

[fumito-ito]

🎉 https://github.com/apple/swift-markdown/releases/tag/0.4.0

[QuietMisdreavus]

Ah, yes, i didn't update this thread. I brought this up with the Swift Documentation Workgroup, and we decided to continue tagging releases based on Swift releases, backporting important bug fixes as necessary. I started off by tagging the 0.4.0 release from the release/5.10 branch, as @fumito-ito spotted. In the future, as major Swift releases (stated subjectively, not referencing the semver number) finish, we will tag more Swift-Markdown releases. For example, when Swift 6.0 reaches its final release, i'll tag 0.5.0 based on the release/6.0 branch. Thanks for your patience, everyone!