diff --git a/docs/admin/installation-binary.md b/docs/admin/installation-binary.md index ef31de7c..513045e2 100644 --- a/docs/admin/installation-binary.md +++ b/docs/admin/installation-binary.md @@ -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: diff --git a/docs/admin/installation-docker.md b/docs/admin/installation-docker.md index db825746..c438d75c 100644 --- a/docs/admin/installation-docker.md +++ b/docs/admin/installation-docker.md @@ -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 diff --git a/docs/admin/upgrade.md b/docs/admin/upgrade.md index da13de07..8ab40e4b 100644 --- a/docs/admin/upgrade.md +++ b/docs/admin/upgrade.md @@ -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 diff --git a/docs/user/api-usage.md b/docs/user/api-usage.md index 10320709..b58d212b 100644 --- a/docs/user/api-usage.md +++ b/docs/user/api-usage.md @@ -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. diff --git a/docs/user/index.md b/docs/user/index.md index e8b3b5eb..9ffd9a21 100644 --- a/docs/user/index.md +++ b/docs/user/index.md @@ -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/) diff --git a/docs/user/semver.md b/docs/user/semver.md deleted file mode 100644 index 5db0b252..00000000 --- a/docs/user/semver.md +++ /dev/null @@ -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: - -- `` is increased for breaking changes. -- `` is increased for backwards-compatible new features. -- `` 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 `..+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: - -- [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"} -``` diff --git a/docs/user/versions.md b/docs/user/versions.md new file mode 100644 index 00000000..ba321de7 --- /dev/null +++ b/docs/user/versions.md @@ -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: + +- `` is increased for breaking changes. +- `` is increased for backwards-compatible new features. +- `` 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 `..+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 + +### Experimental and pre-release versions + +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 + +## 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/).