forgejo-docs/docs/user/versions.md

title	license
Forgejo numbering scheme	CC-BY-SA-4.0

The Forgejo versions looks like X.Y.Z+gitea-A.B.C (e.g. 7.0.0+gitea-1.22.0). The Forgejo version is the first part, before the '+' (e.g. 7.0.0) and the following metadata, after the '+' shows the Gitea version with which the API is compatible (e.g. 1.22.0).

Obtaining the Forgejo version

The Forgejo version is displayed in the footer of the web UI, in the output of the forgejo --version CLI and returned by two API endpoints:

• example.com/api/v1/version
• example.com/api/forgejo/v1/version

For Forgejo 7.0.0 and above, the two endpoints return the same value and they match what is displayed by the CLI or the web UI.

Compatibility with Gitea

As of Forgejo 7.0.0 tools designed to work with Gitea 1.22.0 and below are compatible and do not need any modification to keep working.

In the future, if a tool wants to assert the level of compatibility of a Forgejo version with Gitea, it can:

• Obtain the version number example.com/api/v1/version using the same API endpoint as Gitea
• If the returned version contains '+gitea-', keep what follows as the compatible Gitea version number

For instance Gitnex will not notice a difference when the version number is bumped from Forgejo 1.21.7-0 to Forgejo 7.0.0. It only uses version numbers to verify if a new feature is available in a newer version. The last time such a check was added was with Gitea 1.17 which was published in July 2022.

Semantic Version

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

• <MAJOR> is increased for breaking changes.
• <MINOR> is increased for backwards-compatible new features.
• <PATCH> is increased for backwards-compatible bug fixes.

Forgejo changes reflected in the version 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 are be taken into consideration when creating a new version number.

Stable versions

The structure of the version number is <MAJOR>.<MINOR>.<PATCH>+gitea-<GITEA VERSION>, where:

• <MAJOR>.<MINOR>.<PATCH> is conformant to Semantic Versioning 2.0.0
• gitea-<GITEA VERSION> is the Gitea version this Forgejo release is compatible with

Experimental and pre-release versions

The structure of the version number is <MAJOR>.<MINOR>.<PATCH>-dev-<SHA>+gitea-<GITEA VERSION>, where:

• <MAJOR>.<MINOR>.<PATCH> is conformant to Semantic Versioning 2.0.0
• <SHA> is the Git SHA from which the release was built
• gitea-<GITEA VERSION> is the Gitea version this Forgejo release is compatible with

Legacy forgejo numbering scheme

In Forgejo versions prior to 7.0.0, i.e. from 1.18.0-1 to 1.21.7-0 included, the Forgejo version matched the Gitea version by removing the string following the trailing dash (-) and the release cycles were synchronized.

The version number A.B.C-N was displayed with the dash (-) replaced by a plus (+) (e.g. Forgejo 1.18.0-1 was displayed as 1.18.0+1). The two API endpoints returned different results:

• example.com/api/v1/version returned {"version":"A.B.C+N"}
• example.com/api/forgejo/v1/version returned {"version":"X.Y.Z+N-gitea-A.B.C"}

The Forgejo semantic number X.Y.Z could only be found in the second endpoint and was used to prepare for switching to semantic versioning. It was advertised in release notes and documented in the user reference guide.