foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-12-25 22:40:42 -05:00
Code Issues Activity

Semantic Versioning Updates (#460)

Browse source 
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 <earl-warren@noreply.codeberg.org>
Co-authored-by: inference <admin@inferencium.net>
Co-committed-by: inference <admin@inferencium.net>
This commit is contained in:
inference 2024-03-02 10:54:49 +00:00 committed by Earl Warren
parent 937e55acc0
commit 8e7aa6b332
1 changed files with 24 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
docs/user/semver.md
View file

@ -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.
- `<MAJOR>` is increased for breaking changes.
- `<MINOR>` is increased for backwards-compatible new features.
- `<PATCH>` 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 `<MAJOR>.<MINOR>.<PATCH>+gitea-<GITEA VERSION>`, where:
- `<MAJOR>.<MINOR>.<PATCH>` is conformant to [Semantic Versioning 2.0.0](https://semver.org/#semantic-versioning-200)
- `gitea-<GITEA VERSION>` is the Gitea version this Forgejo release is compatible with
## Understanding the Forgejo pre-release semantic version
The structure of the version number is `<MAJOR>.<MINOR>.<PATCH>-<PRE-RELEASE>+gitea-<GITEA VERSION>`, where:
- `<MAJOR>.<MINOR>.<PATCH>` is conformant to [Semantic Versioning 2.0.0](https://semver.org/#semantic-versioning-200)
- `<PRE-RELEASE>` is the pre-release version, such as a release candidate (`RC`)
- `gitea-<GITEA VERSION>` 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 `<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