From b89f9aac493fc94e42807cd2689396ebe4a07396 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Dachary?= Date: Thu, 16 Mar 2023 09:58:03 +0100 Subject: [PATCH 1/3] 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 `..+-gitea-` where: + +* `..` is conformant to [Semantic Versioning 2.0.0](https://semver.org/#semantic-versioning-200) +* `` is the release build number of an otherwise identical source +* `gitea-` is the Gitea version this Forgejo release depends on From 13875f5860a1509ee7203cde4daf49c6fa7ed7fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Dachary?= Date: Thu, 16 Mar 2023 16:12:51 +0100 Subject: [PATCH 2/3] address Ryuno-Ki review comments --- v1.19/user/semver.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/v1.19/user/semver.md b/v1.19/user/semver.md index a7fe98bf..719ccc36 100644 --- a/v1.19/user/semver.md +++ b/v1.19/user/semver.md @@ -5,9 +5,10 @@ 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. + +- 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 ; From ba7c27a633e10f915fb37a97c3bba8320d94e81e Mon Sep 17 00:00:00 2001 From: KaKi87 Date: Thu, 16 Mar 2023 18:17:14 +0100 Subject: [PATCH 3/3] Typo --- v1.19/user/semver.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/v1.19/user/semver.md b/v1.19/user/semver.md index 719ccc36..2f471faa 100644 --- a/v1.19/user/semver.md +++ b/v1.19/user/semver.md @@ -19,7 +19,7 @@ Since Forgejo has all of the above, changes to all of those components should be ## Getting the Forgejo semantic version -As of Forgejo v1.19, there are two version numbering scheme: +As of Forgejo v1.19, there are two version numbering schemes: * [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