From 8e7aa6b3326926335bcb70601276708604602642 Mon Sep 17 00:00:00 2001 From: inference Date: Sat, 2 Mar 2024 10:54:49 +0000 Subject: [PATCH] Semantic Versioning Updates (#460) Preview: https://forgejo.codeberg.page/@docs_pull_460/docs/next/user/semver/ --- This pull request updates the Semantic Versioning mentions in the Forgejo documentation, as discussed in [forgejo/forgejo #2459](https://codeberg.org/forgejo/forgejo/pulls/2459). It is currently a draft and feedback on how to approach this is appreciated. I think the Forgejo v1.19 section should be renamed to "legacy" or at least mention it due to it being the legacy versioning scheme, and moved below the new SemVer-compliant scheme. You can see how I've done that myself on [my website](https://inferencium.net/about.xhtml#versioning-numbering_scheme) for a taste of how it would look to a user. Reviewed-on: https://codeberg.org/forgejo/docs/pulls/460 Reviewed-by: Earl Warren Co-authored-by: inference Co-committed-by: inference --- docs/user/semver.md | 41 ++++++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/docs/user/semver.md b/docs/user/semver.md index c9bf52ef..5db0b252 100644 --- a/docs/user/semver.md +++ b/docs/user/semver.md @@ -1,22 +1,37 @@ --- -title: Semantic version +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 : +[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: -- Patch is increased for backwards-compatible bugfixes. -- Minor is increased for backwards-compatible new features. -- Major is increased for breaking changes. +- `` is increased for breaking changes. +- `` is increased for backwards-compatible new features. +- `` is increased for backwards-compatible bug fixes. -_something_ could be : +Changes 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. +- 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. +## Understanding the Forgejo stable 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) +- `gitea-` is the Gitea version this Forgejo release is compatible with + +## Understanding the Forgejo pre-release 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 pre-release version, such as a release candidate (`RC`) +- `gitea-` is the Gitea version this Forgejo release is compatible with + ## Getting the Forgejo semantic version As of Forgejo v1.19, there are two version numbering schemes: @@ -35,11 +50,3 @@ For instance, the semantic version for https://code.forgejo.org can be obtained $ 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 `..+-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