Working with source-git #
This document is focused on how Packit treats a source-git repo.
If you are looking for the design concept of source-git, please read it here.
The source-git concept is fairly simple - take an upstream repo and shove downstream content on top of it. Easy right?
Packit is then able to work with such a repo and:
Sync the state into dist-git
And you are able to utilize all features of Packit Service: RPM builds of PRs, tests on those builds, and getting feedback in pull (merge) requests.
Let’s have a look at source-git repo for systemd package:
$ git log --online 67e6197f91 Apply patch 0001-test-path-util-ignore-test-failure.patch 419ec28428 Apply patch 0001-test-path-util-do-not-fail-if-the-fd_is_mount_point-.patch 36d3e907dd Apply patch use-bfq-scheduler.patch 419e249eea add packit.yaml 49615ae7c6 add downstream distribution sources dc057df84c (tag: v247.1) scope: on unified, make sure to unwatch all PIDs once they've been moved to the cgroup scope
We can see 6 commits:
- 67e6197f91 - HEAD commit, a downstream patch
- 419ec28428 - a downstream patch
- 36d3e907dd - a downstream patch
- 419e249eea - a commit with packit.yaml
- 49615ae7c6 - all the downstream sources: spec file, presets, …
- dc057df84c - upstream commit representing the 247.1 release followed by the rest of the upstream history
packit.yaml looks like this:
$ cat .packit.yaml --- specfile_path: "fedora/systemd.spec" upstream_ref: "v247.1" patch_generation_ignore_paths: ["fedora"]
As you can see, we are telling Packit, that commit tagged as
resemble the 247.1 upstream release and the corresponding release tarball which
is used during the build process. Commits on top are converted to patch files
if they change code.
patch-generation-ignore-paths: says that changes to this
paths (files, folders) should not be incorporated into patches:
folder contains all the downstream packaging content.
Rebase or merge? #
A common workflow in the world of open source development is to accept pull or merge requests and have merge commits in the git history. If the PRs are not rebased against the main branch before the merge, the merge commits in the git-history may be heavily intertwined. We are mentioning this because packit works with the recent git history.
Packit is able to work with a git history where merge commits have parents
upstream_ref. When it
detects such state, packit creates an ephemeral branch with linear history and
generates patch files out of it. You can find more details in the pull
request where this was developed.
Picking up latest upstream changes into your downstream source-git repo has multiple solutions and it’s up to you to pick the one which suits your workflow best:
- Rebase against the main upstream branch (a.k.a.
git pull --rebase upstream main). This solution implies that you are able to perform the force-push operation (e.g. Fedora and CentOS dist-git instances don’t allow force-pushes). This solution creates the cleanest git-history though force-pushing is not a best practices for working with a shared git-branch so we suggest to use this only when necessary (e.g. when updating to a new upstream release).
- Create a new branch for every upstream release. No rebase needed — may require good branch hygiene since the number of branches can skyrocket. This is probably the easiest and most straightforward solution.
- Merge upstream changes (a.k.a.
git merge upstream/main). Does not alter existing git history, yet makes it more complicated. You also need to make sure that downstream code changes (meaning, downstream patches) need to be on top of the
upstream_refgit ref so packit can process them correctly.
Common “how-tos” with source-git #
We have subsections covering common downstream maintainer use cases: