diff --git a/docs/configuration/downstream/pull_from_upstream.md b/docs/configuration/downstream/pull_from_upstream.md index c4907d184..fe928c5cf 100644 --- a/docs/configuration/downstream/pull_from_upstream.md +++ b/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: diff --git a/docs/configuration/upstream/propose_downstream.md b/docs/configuration/upstream/propose_downstream.md index 4fbcd249e..8194e7c1a 100644 --- a/docs/configuration/upstream/propose_downstream.md +++ b/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 diff --git a/docs/fedora-releases-guide/index.md b/docs/fedora-releases-guide/index.md index 9c3986f5c..013462b20 100644 --- a/docs/fedora-releases-guide/index.md +++ b/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.