mirror of
https://codeberg.org/forgejo/docs.git
synced 2024-11-21 17:36:59 -05:00
update admin & user guide with semantic versioning
* Explain how the semantic version relate to the API * Update the admin guide terminology * Add a legacy section in the user reference guide
This commit is contained in:
Earl Warren
parent
8e7aa6b332
commit
920b0e97fd
7 changed files with 120 additions and 69 deletions
|
|
@ -16,7 +16,7 @@ and make it executable:
|
|||
|
||||
> **NOTE:** when a line starts with #, it means the command 'foo --bar' must be run as root (or with sudo).
|
||||
|
||||
`# cp forgejo-1.21.5-0-linux-amd64 /usr/local/bin/forgejo`
|
||||
`# cp forgejo-7.0.0-linux-amd64 /usr/local/bin/forgejo`
|
||||
`# chmod 755 /usr/local/bin/forgejo`
|
||||
|
||||
Make sure `git` and `git-lfs` are installed:
|
||||
|
|
|
|||
|
|
@ -6,12 +6,12 @@ license: 'CC-BY-SA-4.0'
|
|||
Forgejo provides [container images](https://codeberg.org/forgejo/-/packages/container/forgejo/versions) for use with Docker or other containerization tools.
|
||||
|
||||
```shell
|
||||
docker pull codeberg.org/forgejo/forgejo:1.21.5-0
|
||||
docker pull codeberg.org/forgejo/forgejo:7.0.0
|
||||
```
|
||||
|
||||
The **1.21** tag is set to be the latest patch release, starting with **1.21.1-0**. The **1.21** tag will then be equal to **1.21.2-0** when it is released and so on.
|
||||
The **7** tag is set to be the latest minor release, starting with **7.0.0**. The **7** tag will then be equal to **7.0.0** when it is released and so on.
|
||||
|
||||
Upgrading from **1.X** to **1.X+1** (for instance from **1.20** to **1.21**) requires a [manual operation and human verification](../upgrade/). However it is possible to use the **X.Y** tag (for instance **1.21**) to get the latest point release automatically.
|
||||
Upgrading from **X** to **X+1** (for instance from **7** to **8**) requires a [manual operation and human verification](../upgrade/). However it is possible to use the **X** tag (for instance **7**) to get the latest minor release automatically.
|
||||
|
||||
Here is a sample [docker-compose](https://docs.docker.com/compose/install/) file:
|
||||
|
||||
|
|
@ -24,7 +24,7 @@ networks:
|
|||
|
||||
services:
|
||||
server:
|
||||
image: codeberg.org/forgejo/forgejo:1.21
|
||||
image: codeberg.org/forgejo/forgejo:7
|
||||
container_name: forgejo
|
||||
environment:
|
||||
- USER_UID=1000
|
||||
|
|
@ -84,7 +84,7 @@ networks:
|
|||
|
||||
services:
|
||||
server:
|
||||
image: codeberg.org/forgejo/forgejo:1.21
|
||||
image: codeberg.org/forgejo/forgejo:7
|
||||
container_name: forgejo
|
||||
environment:
|
||||
- USER_UID=1000
|
||||
|
|
@ -132,7 +132,7 @@ networks:
|
|||
|
||||
services:
|
||||
server:
|
||||
image: codeberg.org/forgejo/forgejo:1.21
|
||||
image: codeberg.org/forgejo/forgejo:7
|
||||
container_name: forgejo
|
||||
environment:
|
||||
- USER_UID=1000
|
||||
|
|
@ -232,8 +232,8 @@ networks:
|
|||
|
||||
services:
|
||||
server:
|
||||
- image: codeberg.org/forgejo/forgejo:1.21
|
||||
+ image: codeberg.org/forgejo/forgejo:1.21-rootless
|
||||
- image: codeberg.org/forgejo/forgejo:7
|
||||
+ image: codeberg.org/forgejo/forgejo:7-rootless
|
||||
container_name: forgejo
|
||||
environment:
|
||||
+ - USER_UID=1024
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ This guide helps Forgejo admins perform upgrades safely and provides guidance to
|
|||
|
||||
## Release life cycle
|
||||
|
||||
There are about two major versions published every year. Each version undergoes the following states:
|
||||
Each Forgejo version undergoes the following states:
|
||||
|
||||
- **Experimental** (current development version): receives new features, should not be used in production
|
||||
- **Stable** (latest major version): receives full support, bugfixes and security fixes
|
||||
|
|
@ -16,9 +16,15 @@ There are about two major versions published every year. Each version undergoes
|
|||
|
||||
To be notified in advance of security releases, watch or subscribe to the RSS feed of the [security-announcements repository](https://codeberg.org/forgejo/security-announcements/issues). The details of the vulnerability will not be revealed, only the expected release date, for administrators to plan ahead and better secure their instance.
|
||||
|
||||
## Semantic version compliance
|
||||
|
||||
Forgejo is compliant with [semantic versioning](https://semver.org/spec/v2.0.0.html) as of 7.0.0. In a nutshell it means that there is no breaking change unless the first number changes (e.g. when 8.0.0 is published it will contain breaking changes compared to 7.0.0). The release notes document those breaking changes and theey may require manual intervention depending on the Forgejo installation.
|
||||
|
||||
In versions prior to 7.0.0, the releases 1.19, 1.20 and 1.21 all contained breaking changes and the versioning scheme was not compliant with semantic versioning.
|
||||
|
||||
## Backup
|
||||
|
||||
To be safe, make sure to perform a full backup before upgrading. It is a requirement when upgrading to a new stable release (going from v1.20 to v1.21 for instance) but is also a good precaution when installing a patch release (going from v1.20.4-0 to v1.20.5-1 for instance).
|
||||
To be safe, make sure to perform a full backup before upgrading. It is a requirement when upgrading to a new stable release (going from v1.20 to v1.21 for instance) but is also a good precaution when installing a minor or patch release (going from v7.0.0 to v7.0.1 for instance).
|
||||
|
||||
The reliable way to perform a backup is with a synchronized point-in-time snapshot of all the storage used by Forgejo.
|
||||
|
||||
|
|
@ -75,9 +81,9 @@ Note: Forgejo requires [docker >= 20.10.6](https://wiki.alpinelinux.org/wiki/Rel
|
|||
[log.file.xorm]
|
||||
FILE_NAME=xorm.log
|
||||
```
|
||||
- If the upgrade from version x.y to version x.y+2 fails and there is a need to narrow down the problem, try upgrading to the latest minor version of each major version and verify it works. It will show which major version causes the issue and help debug the problem. For instance, if upgrading from Forgejo 1.19.3-0 to Forgejo 1.20.5-1 does not work:
|
||||
- Upgrade from Forgejo 1.19.3-0 to Forgejo 1.19.4-0 (the last minor version of the 1.19 major version) and verify Forgejo works.
|
||||
- Upgrade to Forgejo 1.20.5-1 (the last minor version of the 1.20 major version) and verify Forgejo works.
|
||||
- If the upgrade from version x.y to version x.y+2 fails and there is a need to narrow down the problem, try upgrading to the latest version of each series and verify it works. It will show which series causes the issue and help debug the problem. For instance, if upgrading from Forgejo 1.19.3-0 to Forgejo 1.21.6-0 does not work:
|
||||
- Upgrade from Forgejo 1.19.3-0 to Forgejo 1.19.4-0 (the last version of the 1.19 series) and verify Forgejo works.
|
||||
- Upgrade to Forgejo 1.20.6-0 (the last version of the 1.20 series) and verify Forgejo works.
|
||||
|
||||
### Unexpected database version
|
||||
|
||||
|
|
|
|||
|
|
@ -4,6 +4,13 @@ license: 'Apache-2.0'
|
|||
origin_url: 'https://github.com/go-gitea/gitea/blob/d3982bcd814bac93e3cbce1c7eb749b17e413fbd/docs/content/development/api-usage.en-us.md'
|
||||
---
|
||||
|
||||
The Forgejo API for all versions that have the same major number
|
||||
(e.g. the major number of Forgejo 7.0.0 is 7) are compatible. There
|
||||
are breaking changes (e.g. removal of an API endpoint) when the major
|
||||
number changes and the release notes of this major version provide
|
||||
explanations to help developers upgrade their software
|
||||
accordingly. Read more about the [Forgejo numbering scheme](./versions/).
|
||||
|
||||
## Enabling/configuring API access
|
||||
|
||||
By default, `ENABLE_SWAGGER` is true, and `MAX_RESPONSE_ITEMS` is set to 50.
|
||||
|
|
|
|||
|
|
@ -41,9 +41,10 @@ involved in running it on their machines.
|
|||
- [Access Token scope](./token-scope/)
|
||||
- [LDAP, PAM, FreeIPA](./authentication/)
|
||||
- [OAuth2, Client Types](./oauth2-provider/)
|
||||
- [Semantic version](./semver/)
|
||||
- [API Usage](./api-usage/)
|
||||
- [API Reference](https://codeberg.org/api/swagger)
|
||||
- API
|
||||
- [Usage](./api-usage/)
|
||||
- [Forgejo versions](./versions/)
|
||||
- [Reference](https://codeberg.org/api/swagger)
|
||||
- [Migrating Repositories](https://docs.codeberg.org/advanced/migrating-repos/)
|
||||
- [Push to create](./push-to-create/)
|
||||
- [AGit Workflow Usage](./agit-support/)
|
||||
|
|
|
|||
|
|
@ -1,52 +0,0 @@
|
|||
---
|
||||
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:
|
||||
|
||||
- `<MAJOR>` is increased for breaking changes.
|
||||
- `<MINOR>` is increased for backwards-compatible new features.
|
||||
- `<PATCH>` is increased for backwards-compatible bug fixes.
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
- [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
|
||||
{"version":"3.0.0+0-gitea-1.19.0"}
|
||||
```
|
||||
89
docs/user/versions.md
Normal file
89
docs/user/versions.md
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
---
|
||||
title: Forgejo numbering scheme
|
||||
license: '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](https://code.forgejo.org/api/swagger/#/miscellaneous/getVersion)
|
||||
- [example.com/api/forgejo/v1/version](https://code.forgejo.org/api/forgejo/swagger/#/default/getVersion)
|
||||
|
||||
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 Forgejeo 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](https://code.forgejo.org/api/swagger/#/miscellaneous/getVersion) 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](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:
|
||||
|
||||
- `<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](https://semver.org/#semantic-versioning-200)
|
||||
- `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>-<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
|
||||
|
||||
## 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](https://code.forgejo.org/api/swagger/#/miscellaneous/getVersion) returned `{"version":"A.B.C+N"}`
|
||||
- [example.com/api/forgejo/v1/version](https://code.forgejo.org/api/forgejo/swagger/#/default/getVersion) 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](https://forgejo.org/docs/v1.21/user/semver/).
|
||||
Loading…
Reference in a new issue