# PACKAGING WORKFLOW(S) The qemu package follows a special maintenance workflow in order to support git based patching, including of submodules. Please use it in order to have changes you make be acceptable to the package maintainers. All the development happens at https://github.com/openSUSE/qemu. The relevant branch is `factory`. Any change to the package should be submitted in the form of a Pull Request against such repository and branch. The reminder of this document provides more details, explanations and examples for both contributors and maintainers. # FOR CONTRIBUTORS ## BACKPORTING AN UPSTREAM PATCH For submitting a backport of an upstream patch, proceed as follows (a local copy of the repository is of course necessary). Identify the hash of the commit that needs backporting and do: git cherry-pick -esx This way, the changelog will already contain the reference to the upstream commit itself, and the appropriate "Signed-off-by:" tag. If the backport is related to Bugzilla (or Jira, and/or CVEs, etc) entry, add a reference to that, such as: Resolves: bsc#123456 Or: References: jsc#PED-1234 Or: Resolves: bsc#7891011 (CVE-1234-5678) Add it between the "(cherry picked from commit ...)" line and the "Signed-off-by:" line that follows it. An example of the end result, where Dario Faggioli () is backporting upstream commit abe2c4bdb65e8dd in order to fix bug 1209546 from bugzilla.opensuse.org is: test-vmstate: fix bad GTree usage, use-after-free According to g_tree_foreach() documentation: "The tree may not be modified while iterating over it (you can't add/remove items)." [...] Get rid of the node removal within the tree traversal. Also check the trees have the same number of nodes before the actual diff. Fixes: 9a85e4b8f6 ("migration: Support gtree migration") Resolves: https://gitlab.com/qemu-project/qemu/-/issues/1518 Signed-off-by: Marc-Andr303251 Lureau Signed-off-by: Eric Auger Reported-by: Richard W.M. Jones Tested-by: Richard W.M. Jones Reviewed-by: Richard W.M. Jones Reviewed-by: Daniel P. Berrang303251 Reviewed-by: Juan Quintela Signed-off-by: Juan Quintela (cherry picked from commit abe2c4bdb65e8dd9cb2f01c355baa394bf49a8af) Resolves: bsc#1209546 Signed-off-by: Dario Faggioli Of course, all conflicts and issues should be resolved, before committing the result/completing the cherry-picking. At this point, the PR should be opened. As soon as that happens, some checks will be run automatically and the maintainers of the QEMU package will review and, eventually, merge or reject it. PRs containing multiple commits are allowed. They are actually encouraged, if the patches being backported are related and/or dependant among each others. It must, however, always be the case that each upstream commit is cherry-picked individually. Note that there is no need to change any 'qemu.changes' file. That will, in fact be handled by the package maintainers (and such RPM changelog entries will be automatically generated out of the git commit messages). ## ADDING A PATCH NOT COMING FROM UPSTREAM Downstream patches, i.e., patches that are not backports of upstream commits, should be avoided as much as possible. The (largely!) recommended approach is to submit the patch upstream and then, once it is accepted and committed, backport it. If that is not possible (for whatever reason), a pull request with a downstream only patch can be opened. The procedure is almost identical to the one described above for upstream backports. The main differences are: 1) Downstream only patch cannot be cherry-picked from upstream commits, of course. Therefore, the PR will consist of the commit(s) that introduces the patch. 2) There will be no "(cherry picked from commit ...") line in the changelog of a downstream only patch. On the other hand, the "Resolves:" or "Reference:" tag, that link the patch to the issue it's trying to solve, must be there, and the same is true for the "Signed-off-by:" tag indicating who is proposing adding it. 3) It is required that the subject of the commit starts with the [openSUSE] tag. An example of a downstream only commit is: [openSUSE] pc: q35: Bump max_cpus to 1024 And use the new limit for machine version 7.1 too. Keep the old limit of 288 for machine versions 7.0 and earlier. Signed-off-by: Dario Faggioli References: bsc#1202282, jsc#PED-2592 Signed-off-by: Dario Faggioli ## CHANGING THE PACKAGING FILES Files that are necessary for building the RPM (like the spec file) or that are part of the RPM and will be copied in the appropriate places in the filesystem when it is installed are also part of the git repository. In fact, they can be found in the `rpm/` directory. Any addition, removal or change of and on any of those file should just be done as a regular commit, and a pull request including such commit(s) should be opened. Commits to packaging files should be prefixed with both the [openSUSE] tag and an [RPM] tag. An example can be this one: [openSUSE][RPM] Add downstream packaging files Stash the "packaging files" in the QEMU repository, in the rpm/ directory. During package build, they will be pulled out from there and used as appropriate. Signed-off-by: Dario Faggioli ## ADDING A PATCH IN A SUBMODULE For including a backport, or in general adding a patch, to a submodule, the downstream git repository for the submodule must be checkedout at the location where the submodule resides, in the main QEMU git repository. For example, for including a downstream patch in the ipxe submodule, a local copy of the repository https://github.com/openSUSE/qemu-ipxe.git is necessary. After checking out the `factory` branch, add the patch there (cherry-picking it from upstream, if it is a backport, and respecting all the tagging rules explained in the previous sections). At this point: - the branch must be pushed; - in the main (qemu) repository, a commit must be added and pushed, for making sure that the new patch is picked up. Basically, the commit in the main repository is how the information that a submodule as a new head is recorded. The changelog of such commit shall include a reference to the subjects of all the new commits in the various submodules. Unfortinately, there is not yet a good way of achieving this automatically. As last step, a pull request should be opened, as usual. ## REMOVING PATCHES If a patch, or, in general, a commit, that is already part of the repository must be removed, this must be done without rewriting the git history, i.e., with a revert (and then a pull request with the revert should be opened). # FOR MAINTAINERS ## REVIEWING AND ACCEPTING PRs TODO ## COMMITTING CHANGES INTO FACTORY TODO ## UPDATING THE BASE QEMU VERSION TODO # MANUAL AND AUTOMATED CHECKS TODO