forgejo-docs/user/semver.md

layout	title	license
~/layouts/Markdown.astro	Semantic version	CC-BY-SA-4.0

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