From e09dcd0caa24f7ed377a8fab274f37245277312e Mon Sep 17 00:00:00 2001 From: Hunor Csomortáni Date: May 07 2021 14:16:44 +0000 Subject: WIP: design and workflow proposal Signed-off-by: Hunor Csomortáni --- diff --git a/source-git-workflow.md b/source-git-workflow.md new file mode 100644 index 0000000..729555f --- /dev/null +++ b/source-git-workflow.md @@ -0,0 +1,142 @@ +# Source-git design + +## About source-git + +Content of source-git repository is equivalent to dist-git, but uses upstream +format. This means that upstream sources are present as upstream Git-history, +not an archive created from upstream Git-history as in dist-git. + +With this setup we aim to allow package maintainers to use modern Git-tools to +patch and update their packages. + +Source-git repositories are meant as an add-on on top of dist-git. This means +that while dist-git will continue to be the authoritative place for source +code, work can be done in source-git and tooling will help with keeping the +two places in sync. + +## Design goals + +### Compatibility with dist-git + +### Consistency across packages + +### Respect Fedora Packaging Guidelines + +## Layout and structure + +## Workflow + +### Creating a source-git repository + +In order to construct a source-git repository the following steps need to be +taken: + +1. Pick the upstream revision (version tag, branch or commit) in the upstream + Git repository which serves as the base for downstream development and + start a downstream branch from it. +2. Take packaging related files (like spec-file, scripts), place them in a + `.distro` subdirectory and commit them. +3. Apply the downstream patches (found in the corresponding dist-git + repository, at a selected revision) as defined in the spec-file as Git + commits. + +Running a command similar to the one below would perform the steps above. The +upstream repo and a revision of it and the corresponding dist-git repo and a +selected revision of it would serve as input for this command, specified as a +local path or URL. + + $ packit init --upstream-url --upstream-ref \ + --dist-git-path --dist-git-branch + +### Introducing a downstream change + +Creating a change downstream (in the distribution) would be similar to +creating a change in the upstream repository: + +1. Start with the downstream branch to be updated. +2. Do the change or cherry-pick commits from upstream branches. +3. Commit, push and open an PR. +4. Automation takes the source-git PR, transforms it and opens a mirror PR in + dist-git. This way CI results produced in dist-git could be mirrored back + to source-git. Automation keeps the dist-git PR up to date as the + source-git PR is updated. +5. After approval the source-git PR is merged. TODO(csomh): this needs to be + better defined, as there might be some non-trivial orchestration needed in + order to ensure consistency and avoid race-conditions. + +### Rebasing a distribution branch to a new upstream version + +Downstream (distribution) history might diverge from +upstream, and so some packages might have a need to rebase these downstream +branches. + +These rebases can potentially be "hard case" rebases, where conflicts need to +be resolved during the rebase. + +Tooling should help contributors to review and test such rebases, and to +recover their working branches after a rebase. + +#### Proposing rebases + +Proposing a rebase to a new rev of upstream would be done using a dedicated +branch. Lacking a better name, let’s call them rebase-proposal branches. + +Rebase-proposal branches would be named as `-` +or(?) `--`. For example: +`f34-0000001` or `f34-0000001-2.23.4.g1233`. + +These branches would be kept "forever" and would serve as a way to track the +history of the rebases. This would be achieved by relying on the +`` component of the branch names. Tooling would take care of +implementing this index in a consistent manner. + +The `` component of the branch names could make more obvious +which upstream rev was the parent of the rebase-proposal branch. Not sure if +this would be actually useful or something wanted. + +The process would be as follows: +1. Checkout a rebase-proposal branch from the downstream distribution branch. +2. Rebase the rebase-proposal branch to the new upstream revision. +3. Push the rebase-proposal branch and open a PR. + + $ git fetch upstream + $ git checkout -b f34-0000001-2.23.4.g1233 f34 + $ git rebase v2.23.4 f34-0000001-2.23.4.g1233 + $ git push -u origin f34-0000001-2.23.4.g1233 + +Some of the commands above could be wrapped in a rpkg clones. Something like: + + $ fedpkg propose-rebase v2.23.4 f34 + +Open a PR and review. Label the MR with "rebase". This will block the MR to be +merged, while it can be used for reviews and testing. After the rebase is +approved: + + $ git checkout f34 + $ git reset --hard f34-0000001-2.23.4.g1233 + $ git push --force-with-lease source-git f34 + +The Git-forge (i.e. Pagure) would only accept a force push for the f34 branch +if the target commit is flagged as tested and approved for rebases and the +target commit is the head of a "rebase-proposal" branch. + +#### Rebasing WIP after a distribution branch rebase + +Recreate the local f34 branch and fetch all other branches from source-git. + +On a feature branch: +1. Find the nearest "rebase proposal" branch. +2. Rebase commits since that branch onto f34. +3. Force push. + +### Building a new release + +This is just a bump in the release number. Doing it through source-git will +introduce unnecessary friction: time will be spent to sync the change to +dist-git, and only then the build can be triggered. How can this be improved? + +## Tooling + +### Local (CLI) + +### Remote (aka services)