Document pre-releases (#777)

Document pre-releases

Reviewed-by: Laura Barcziová
Reviewed-by: Nikola Forró

docs/archive-not-matching-git.md

@@ -1,6 +1,6 @@
 ---
 title: Generated code in upstream archives
-sidebar_position: 10
+sidebar_position: 11
 ---
 
 # When the release archive does not match the upstream git tag checkout

docs/configuration/index.md

@@ -533,6 +533,27 @@ should trigger a reaction.
 - in Packit Service: In `propose_downstream` and `pull_from_upstream` jobs, it determines whether a specific release 
 should trigger a reaction.
 
+#### prerelease_suffix_pattern
+(*string*) This field requires a partial Python regex pattern. It is used to match recognized pre-release suffixes.
+The first capturing group must capture the delimiter between a base version and a pre-release suffix and can be empty
+in case there is no delimiter. It defaults to `([.\-_~^]?)(alpha|beta|rc|pre(view)?)([.\-_]?\d+)?`.
+This is a safe default that shouldn't produce any false positives and you may need to adjust it if your project uses
+a different versioning scheme.
+
+For example, you can use the following regex to conform to [PEP440](https://peps.python.org/pep-0440/):
+
+    prerelease_suffix_pattern: "([.\\-_]?)(a(lpha)?|b(eta)?|r?c|pre(view)?)([.\\-_]?\\d+)?"
+
+Or you can undefine the option to opt-out from pre-release processing:
+
+    prerelease_suffix_pattern: null
+
+#### prerelease_suffix_macro
+(*string*) Name of a macro that controls whether spec file version is a pre-release and contains the pre-release suffix.
+If Packit detects, based on [`prerelease_suffix_pattern`](#prerelease_suffix_pattern), a pre-release version,
+this macro will be uncommented, otherwise it will be commented out. See [pre-releases with Packit](/docs/pre-releases)
+for more details.
+
 
 ## Aliases
 

docs/cross-project-testing.md

@@ -1,6 +1,6 @@
 ---
 title: Setting up cross-project testing
-sidebar_position: 9
+sidebar_position: 10
 ---
 # Setting up cross-project testing
 Cross-project testing enables you to ensure the compatibility and reliability of interconnected repositories.
@@ -96,4 +96,4 @@ Make sure to also give it a meaningful `identifier` so that you can differentiat
           tmt:
             context:
               revdeps: "yes"
-```
+```

docs/pre-releases.md

@@ -0,0 +1,92 @@
+---
+title: Pre-releases
+sidebar_position: 9
+---
+# Setting up pre-releases with Packit
+
+There are two ways how to support pre-releases in a spec file.
+
+The simpler way relies on the `%version_no_tilde` macro from `rust-srpm-macros` (not present on EL < 9)
+that converts a pre-release version with `~` back to upstream version. An optional argument defines upstream delimiter
+that defaults to `-`.
+Here is an example of a spec file using this macro:
+
+```specfile
+Version:        3.28.0~rc3
+
+...
+
+Source0:        https://example.com/files/v%{version_no_tilde}/%{name}-%{version_no_tilde}.tar.gz
+
+...
+
+%prep
+%autosetup -p1 -n %{name}-%{version_no_tilde}
+```
+
+If upstream version doesn't have a delimiter, for example `3.28.0b5`, you can use `%{version_no_tilde %{quote:%nil}}`.
+
+The second, more complex way requires you to define a macro, typically called `prerelease` or `prerel`, and package version
+(value of the `Version` tag) and upstream version are constructed depending on whether it is defined or commented out.
+Here is an example of such a spec file:
+
+```specfile
+%global base_version 3.28.0
+%global prerelease rc3
+
+%global package_version %{base_version}%{?prerelease:~%{prerelease}}
+%global upstream_version %{base_version}%{?prerelease:-%{prerelease}}
+
+...
+
+Version:        %{package_version}
+
+...
+
+Source0:        https://example.com/files/v%{upstream_version}/%{name}-%{upstream_version}.tar.gz
+
+...
+
+%prep
+%autosetup -p1 -n %{name}-%{upstream_version}
+```
+
+And a bit more complex example that achieves the same (but this time there is no delimiter in upstream version
+and tarball URL is slightly different):
+
+```specfile
+%global majorver 3
+%global minorver 28
+%global patchver 0
+%global prerel rc3
+
+%if 0%{?prerel:1}
+%global package_version %{majorver}.%{minorver}.%{patchver}~%{prerel}
+%global upstream_version %{majorver}.%{minorver}.%{patchver}%{prerel}
+%else
+%global package_version %{majorver}.%{minorver}.%{patchver}
+%global upstream_version %{majorver}.%{minorver}.%{patchver}
+%endif
+
+...
+
+Version:        %{package_version}
+
+...
+
+Source0:        https://example.com/files/v%{majorver}.%{minorver}/%{name}-%{upstream_version}.tar.gz
+
+...
+
+%prep
+%autosetup -p1 -n %{name}-%{upstream_version}
+```
+
+Packit supports both ways. There is a config option [`prerelease_suffix_pattern`](/docs/configuration#prerelease_suffix_pattern)
+that defines a regex that is used to determine if a version is a pre-release or not.
+It defaults to `([.\-_~^]?)(alpha|beta|rc|pre(view)?)([.\-_]?\d+)?` and you can adjust it if your project uses
+a different versioning scheme or undefine it to opt-out from pre-release processing. The first capturing group of the regex
+should capture the delimiter and can be empty if there is none.
+If a pre-release is detected, the delimiter is replaced with `~` to ensure proper sorting by RPM. You can also configure
+the [`prerelease_suffix_macro`](/docs/configuration#prerelease_suffix_macro) option to correspond to a pre-release macro
+in your spec file and this macro will be commented out or uncommented accordingly.

docs/reproduce-locally.md

@@ -1,7 +1,7 @@
 ---
 title: Reproduce CI environment locally
 date: 2022-03-01
-sidebar_position: 10
+sidebar_position: 12
 ---
 
 # Reproduce CI environment locally

docs/service-level-objectives.md

@@ -1,7 +1,7 @@
 ---
 title: Service Level Objectives
 date: 2022-03-31
-sidebar_position: 10
+sidebar_position: 12
 ---
 
 # Service Level Objectives