Add docs for non diverge branches with Packit (#931)

docs/configuration/downstream/pull_from_upstream.md

@@ -69,8 +69,19 @@ Use a repository you maintain as we will create issues about failures here.
 
 ## Optional parameters
 
-* **dist_git_branches** - a (list of) branch(es) in dist-git where packit should work (defaults to `main`).
-  You can also use the [aliases provided by Packit](/docs/configuration#aliases)
+* **dist_git_branches** 
+  - a (list of) branch(es) in dist-git where packit should work (defaults to `main`).
+  - or a dict whose *keys* are the names of the dist-git branches where packit synchronizes release changes 
+  and the *values* are in the form of an empty dict `{}` or as 
+  `{fast_forward_merge_into: [other branches names]}`. In the second example, packit tries to fast forward
+  the changes created for the *key branch* in the *other branches* opening a pull request for them.
+
+:::info
+For how to keep dist-git branches non divergent 
+please see the details [here](/docs/fedora-releases-guide#keeping-dist-git-branches-non-divergent).
+:::
+
+  As branch names you can use the [aliases provided by Packit](/docs/configuration#aliases)
   to not need to change the config file when the new system version is released.
 
 :::tip 
@@ -80,12 +91,6 @@ For more details and customization options, also check
 
 :::
 
-
-:::info
-Current default behaviour of the release syncing results in having divergent dist-git branches. If you want to avoid this,
-please see the details [here](/docs/fedora-releases-guide#keeping-dist-git-branches-non-divergent).
-:::
-
 ## Retriggering
 Packagers can retrigger the job
 via a comment in any dist-git pull request:

docs/configuration/upstream/propose_downstream.md

@@ -48,16 +48,23 @@ configuration specifics, see [the subsection below](#syncing-the-release-to-cent
 
 ## Optional parameters
 
-* **dist_git_branches** - a (list of) branches in dist-git where packit should work (defaults to `main` which represents _Fedora Rawhide_).
-  You can also use the [aliases provided by Packit](/docs/configuration#aliases)
-  to not need to change the config file when the new system version is released.
-
-* [**notifications.failure_issue.create**](/docs/configuration#failure_issue) - whether to create an upstream issue about failure. Defaults to `true`.
+* **dist_git_branches** 
+  - a (list of) branches in dist-git where packit should work (defaults to `main` which represents _Fedora Rawhide_).
+  - or a dict whose *keys* are the names of the dist-git branches where packit synchronizes release changes 
+  and the *values* are in the form of an empty dict `{}` or as 
+  `{fast_forward_merge_into: [other branches names]}`. In the second example, packit tries to fast forward
+  the changes created for the *key branch* in the *other branches* opening a pull request for them.
 
 :::info
-Current default behaviour of the release syncing results in having divergent dist-git branches. If you want to avoid this,
+For how to keep dist-git branches non-divergent 
 please see the details [here](/docs/fedora-releases-guide#keeping-dist-git-branches-non-divergent).
 :::
+
+  As branch names you can also use the [aliases provided by Packit](/docs/configuration#aliases)
+  to not need to change the config file when the new system version is released.
+
+* [**notifications.failure_issue.create**](/docs/configuration#failure_issue) - whether to create an upstream issue about failure. Defaults to `true`.
+
 
 ## Example
 

docs/fedora-releases-guide/index.md

@@ -217,26 +217,56 @@ for overriding the Packit default behaviour, for example:
   - for **source archive(s) generation**, you can utilise e.g. `pre-sync` action, see 
   [this example](/docs/configuration/examples#custom-archive-creation-for-release-syncing)
 
-#### Keeping dist-git branches non-divergent
-Packit currently syncs the release in a way that the branches become divergent (you can follow 
-the request to change this behaviour [here](https://github.com/packit/packit/issues/1724)). 
-
-However, if you wish to keep your dist-git branches in sync, you can configure Packit to propose updates exclusively 
-to `rawhide` (by specifying `dist_git_branches: fedora-rawhide`) and you can locally merge it with the stable release branches. 
-The following example demonstrates how to achieve this for a single branch (`f39` in this case):
-```bash
-# Clone the dist-git repository if you haven't done so already
-fedpkg clone $PACKAGE
-# or
-git clone ssh://$YOUR_USER@pkgs.fedoraproject.org/rpms/$PACKAGE.git
-
-# Alternatively, pull the rawhide changes only
-git pull origin rawhide
-
-# Switch to the desired branch and merge it with the updated rawhide branch
-git checkout f39
-git merge rawhide
-git push origin f39
+#### Keep dist-git branches non-divergent
+
+If you want to keep your dist-git branches from diverging,
+you can use the new `dist_git_branches` syntax:
+
+```yaml
+  dist_git_branches:
+    rawhide:
+      fast_forward_merge_into: [fedora-branched]
+    epel-9: {}    
+      
+```
+
+In this example, Packit runs the downstream synchronization process for the
+`rawhide` and `epel-9` branches as usual. But Packit also opens a new pull request reusing the commit from `rawhide` for every
+`fedora-branched` branch so it can be fast-forwarded when merging.
+
+:::warning How to reconcile divergent branches
+
+If you are already using Packit then your branches can have diverged.
+You need to reconcile them before using the new dist_git_branches 
+syntax.
+For the configuration example above and for the state of the branched
+Fedora releases as today, you need to do:
+
+```
+git checkout rawhide
+git merge f39
+git merge f40
+git merge f41
+```
+
+You shouldn't have any conflict.
+But, if you have a conflict in the `.gitignore` file it is safe to 
+keep changes both from rawhide and the incoming branch.
+If you have a conflict in the changelog section of the specfile,
+then you must pay attention to **merge all the missing changelogs** 
+in rawhide and to list them **in the right order** 
+(newest changelogs come first). 
+Once rawhide is ready you can do
+
+```
+git checkout f39; git merge --ff-only rawhide
+git checkout f40; git merge --ff-only rawhide
+git checkout f41; git merge --ff-only rawhide
+```
+
+:::
+
+
 ```
 ## Koji build job
 After having the dist-git content updated, you can easily automate also building in Koji.