Blogpost-no-divergent-branches (#957)

Fixes #938

docs/configuration/downstream/pull_from_upstream.md

@@ -78,7 +78,7 @@ Use a repository you maintain as we will create issues about failures here.
 
 :::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).
+please see the details [here](/docs/fedora-releases-guide/non-divergent-dist-git-branches.md).
 :::
 
   As branch names you can use the [aliases provided by Packit](/docs/configuration#aliases)

docs/configuration/upstream/propose_downstream.md

@@ -57,7 +57,7 @@ configuration specifics, see [the subsection below](#syncing-the-release-to-cent
 
 :::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).
+please see the details [here](/docs/fedora-releases-guide/non-divergent-dist-git-branches.md).
 :::
 
   As branch names you can also use the [aliases provided by Packit](/docs/configuration#aliases)

docs/fedora-releases-guide/dist-git-onboarding.md

@@ -88,8 +88,7 @@ and not from `upstream_project_url`.
 You can check the other customization options [here](./index.md#customization).
 
 :::info Divergent dist-git branches
-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).
+By default, release syncing can result in divergent dist-git branches. To prevent this, refer to the configuration details [here](/docs/fedora-releases-guide/non-divergent-dist-git-branches.md).
 :::
 
 

docs/fedora-releases-guide/index.md

@@ -197,6 +197,8 @@ you should specify the [`upstream_tag_template`](/docs/configuration/#upstream_t
 via [`files_to_sync`](/docs/configuration/#files_to_sync) configuration key.
 - By default, Packit downloads sources defined in the spec file that contain URLs.
 You can override these URLs via [`sources`](/docs/configuration#sources) configuration key.
+- By default, release syncing can result in divergent dist-git branches. To prevent this, refer to the configuration details [here](/docs/fedora-releases-guide/non-divergent-dist-git-branches.md).
+
 
 ##### Actions - use your own commands/scripts
 - You may utilise some of the [actions](/docs/configuration/actions/#syncing-the-release)
@@ -217,55 +219,6 @@ 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)
 
-#### 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.

docs/fedora-releases-guide/non-divergent-dist-git-branches.md

@@ -0,0 +1,49 @@
+---
+title: Non-divergent dist-git branches
+sidebar_position: 7
+---
+
+# Non-divergent dist-git branches
+
+To prevent your dist-git branches from diverging, you can use the following `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. Additionally, Packit opens a new pull request reusing the commit from `rawhide` for every `fedora-branched` branch, allowing it to be fast-forwarded when merging.
+
+You can learn more about the `dist_git_branches` syntax for `propose_downstream` [here](docs/configuration/upstream/propose_downstream#optional-parameters) and for `pull_of_upstream` [here](docs/configuration/downstream/pull_from_upstream#optional-parameters).
+
+:::warning How to Reconcile Divergent Branches
+
+If you are already using Packit, your branches may have diverged. You need to reconcile them before using the new `dist_git_branches` syntax. For the configuration example above and the current state of the branched Fedora releases, you need to:
+
+```
+git checkout rawhide
+git merge f39
+git merge f40
+git merge f41
+```
+
+You shouldn't encounter any conflicts. However, if you have a conflict in the `.gitignore` file, it is safe to keep changes from both `rawhide` and the incoming branch. If you have a conflict in the changelog section of the specfile, ensure you **merge all the missing changelogs** into `rawhide` and list them **in the correct order** (newest changelogs first). Once `rawhide` is ready, you can proceed with:
+
+```
+# [TODO] Adjust the releases, if needed.
+git checkout f39; git merge --ff-only rawhide
+git checkout f40; git merge --ff-only rawhide
+git checkout f41; git merge --ff-only rawhide
+```
+
+:::
+
+:::warning Fast Forwarding multiple commits does not automatically trigger a Koji build (Yet)
+
+Unfortunately, there is a [bug](https://github.com/packit/packit-service/issues/2537) that prevents Packit from triggering the **Koji build** when more than one commit has been forwarded in a branch.
+
+You can work around this bug by manually retriggering the Koji build by commenting on the downstream merged pull request with `/packit koji-build`.
+
+:::

posts/non-divergent-dist-git-branches/index.md

@@ -0,0 +1,29 @@
+---
+title: "No more divergent dist-git branches with Packit!"
+date: 2024-10-28T10:46:18+00:00
+authors: mmassari
+tags:
+  - propose-downstream
+  - pull-from-upstream
+  - downstream
+  - configuration
+---
+
+Were you annoyed by Packit creating divergent branches in your package's dist-git repository? You'll be happy to know that Packit now supports a new `dist_git_branches` syntax that enables fast-forwarding commits between branches.
+
+<!--truncate-->
+
+## What's New
+
+When defining a `propose-downstream` or `pull-from-upstream` job, you can use the new `dist_git_branches` syntax.
+
+```
+  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. Additionally, Packit opens a new pull request, reusing the commit from `rawhide`, for every `fedora-branched` branch, allowing it to be fast-forwarded when merging.
+
+Do you want to know more? Look at the [non-divergent dist-git branches guide](/docs/fedora-releases-guide/non-divergent-dist-git-branches)