version_update_mask related docs and changes (#772)

Merge after packit/packit-service#2250

docs/configuration/actions.md

@@ -65,8 +65,8 @@ These apply to `propose-downstream` command/job and `pull-from-upstream` job.
 
 |        | name                  | working directory | when run                                                              | description                             |
 |--------|-----------------------|-------------------|-----------------------------------------------------------------------|-----------------------------------------|
-| [hook] | `post-upstream-clone` | upstream git repo | after cloning of the upstream repo (main) and before other operations |                                         |
-| [hook] | `pre-sync`            | upstream git repo | after cloning and checkout to the correct (release) branch            |                                         |
+| [hook] | `post-upstream-clone` | upstream git repo | after cloning the upstream repo (main) and dist-git repo (target branch) and before gpg keys verification and version compatibility check |                               |
+| [hook] | `pre-sync`            | upstream git repo | after cloning the upstream repo (main) and dist-git repo (target branch) and after gpg keys verification and version compatibility check |                               |
 |        | `prepare-files`       | upstream git repo | after cloning, checking out of both upstream and dist-git repos       | replace patching and archive generation |
 |        | `create-patches`      | upstream git repo | after sync of upstream files to the downstream                        | replace patching                        |
 |        | `get-current-version` | upstream git repo | when the current version needs to be found                            | expect version as a stdout parameter    |
@@ -246,8 +246,8 @@ when syncing upstream release downstream, e.g. `rhbz#123 rhbz#124`
 
 Related to the `propose-downstream` and `pull-from-upstream` jobs.
 
-* `PACKIT_UPSTREAM_REPO` — absolute path to cloned upstream git repo
-* `PACKIT_DOWNSTREAM_REPO` — absolute path to cloned downstream git repo
+* `PACKIT_UPSTREAM_REPO` — absolute path to cloned upstream git repo (main branch) 
+* `PACKIT_DOWNSTREAM_REPO` — absolute path to cloned downstream git repo (target branch)
 
 List of actions that provide these environment variables:
 * `post-upstream-clone`

docs/configuration/index.md

@@ -555,6 +555,18 @@ this macro will be uncommented, otherwise it will be commented out. See [pre-rel
 for more details.
 
 
+#### version_update_mask
+(*string*) This field can be used to filter upstream versions when syncing the releases e.g. to avoid main version bump on the stable Fedora version.
+This check **does not run for the rawhide branch**, if you want to skip releases in rawhide use *upstream_tag_exclude*.
+The value requires a Python regex pattern and is used with `re.match` function.
+ The old version contained in the *dist-git target branch specfile* and the *newly released version in upstream* 
+ have both to match this reg exp and the matching value has to be the same otherwise Packit will not sync the 
+ release downstream.
+ Take as an example a `version_update_mask` set to `\d+\.\d+\.`, 
+ *3.8.0* as specfile *version*  and  *3.9.0* as a new upstream *release tag*, the versions are matching but the 
+ matched values are not the same, thus Packit will not create a *3.9.0*  pull request release on dist-git target 
+ branch. If there is an *3.8.1* release, the matched values (=`3.8`) are the same and pull request is created.
+
 ## Aliases
 
 To not need to change the config file when the new system version is released,