From b89f9aac493fc94e42807cd2689396ebe4a07396 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Dachary?= <loic@dachary.org>
Date: Thu, 16 Mar 2023 09:58:03 +0100
Subject: [PATCH] add section about semantic version

---
 v1.19/user/index.md  |  1 +
 v1.19/user/semver.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+)
 create mode 100644 v1.19/user/semver.md

diff --git a/v1.19/user/index.md b/v1.19/user/index.md
index fa15e6bb..3ee20ad5 100644
--- a/v1.19/user/index.md
+++ b/v1.19/user/index.md
@@ -33,6 +33,7 @@ involved in running it on their machines.
   - Authentication
     - [LDAP, PAM, FreeIPA](authentication)
     - [OAuth2, Scoped Tokens, Client Types](oauth2-provider)
+  - [Semantic version](semver)
   - [API Usage](api-usage)
   - [API Reference](https://codeberg.org/api/swagger)
   - [Migrating Repositories](https://docs.codeberg.org/advanced/migrating-repos/)
diff --git a/v1.19/user/semver.md b/v1.19/user/semver.md
new file mode 100644
index 00000000..a7fe98bf
--- /dev/null
+++ b/v1.19/user/semver.md
@@ -0,0 +1,44 @@
+---
+layout: '~/layouts/Markdown.astro'
+title: Semantic version
+license: 'CC-BY-SA-4.0'
+---
+
+[SemVer](https://semver.org/spec/v2.0.0.html) allows users to understand the scope of a software update at first glance, based on the following :
+- the patch number is incremented when something is fixed ;
+- the minor number is incremented when something is added ;
+- the major number is incremented when something is moved or removed.
+
+*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 scheme:
+
+* [Following the Gitea version](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/CONTRIBUTING/RELEASE.md#release-numbering) 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:
+
+```shell
+$ curl https://code.forgejo.org/api/forgejo/v1/version
+{"number":"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](https://semver.org/#semantic-versioning-200)
+* `<build>` is the release build number of an otherwise identical source
+* `gitea-<gitea version>` is the Gitea version this Forgejo release depends on