Semantic version

SemVer allows users to understand the scope of a software update at first glance, based on the following :

  • Patch is increased for backwards-compatible bugfixes.
  • Minor is increased for backwards-compatible new features.
  • Major is increased for breaking changes.

something could be :

  • a command, an option or an argument, for a CLI ;
  • a route path, a query parameter or a body property, for a REST API ;
  • a text node, a button or a field, for a GUI.

Since Forgejo has all of the above, changes to all of those components should be taken into consideration when creating a new version number.

Getting the Forgejo semantic version

As of Forgejo v1.19, there are two version numbering schemes:

  • Following the Gitea version which is not a semantic version
    • Used to name release files
    • Used for tagging releases
    • Displayed in the web interface
    • Returned by the /api/v1/version API endpoint
  • Forgejo semantic version
    • Returned by the /api/forgejo/v1/version API endpoint

For instance, the semantic version for https://code.forgejo.org can be obtained with:

$ curl https://code.forgejo.org/api/forgejo/v1/version
{"version":"3.0.0+0-gitea-1.19.0"}

Understanding the Forgejo semantic version

The structure of the version number is <major>.<minor>.<patch>+<build>-gitea-<gitea version> where:

  • <major>.<minor>.<patch> is conformant to Semantic Versioning 2.0.0
  • <build> is the release build number of an otherwise identical source
  • gitea-<gitea version> is the Gitea version this Forgejo release depends on