From e24141fc1d0a7875a6e4c514c3ce77094a21254f Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Tue, 20 Oct 2020 20:16:47 +0200 Subject: [PATCH] Improve README layout + some small fixes - Format some text as monospaced text - Break up wall of text into separate sections where possible - Use one sentence per line (this way it's easier to see what a pull request changes, and it's easier to maintain) - Italicize Dependabot, Depfu and Renovate brand names - Change word consier -> consider --- README.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8255274..9363e03 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,25 @@ # Combine PRs -This GitHub Workflow allows you to combine a number of PRs into a single one, by merging the branches for each PR into a new branch and opening a PR for it. Specifically, it was created to group Dependabot PRs together, but it is generic enough that it can be used with other services that create PRs with branch names that have a specific prefix (such as dependabot/{branchname} in the case of dependabot). +This GitHub Workflow allows you to combine a number of PRs into a single one, by merging the branches for each PR into a new branch and opening a PR for it. Specifically, it was created to group Dependabot PRs together, but it is generic enough that it can be used with other services that create PRs with branch names that have a specific prefix (such as `dependabot/{branchname}` in the case of dependabot). ![Combined PR](/images/combined-pr.png?raw=true "Combined PR") # Get started -To use this, copy [combine-prs.yml](combine-prs.yml) into your repository to the folder .github/workflows/ and commit and push it to GitHub. Then on GitHub, click the 'Actions' tab at the top of your repository, then under 'All workflows' on the left click 'Combine PRs', and finally on the righthand side, click 'Run workflow'. +To use this, copy [combine-prs.yml](combine-prs.yml) into your repository to the folder `.github/workflows/` and commit and push it to GitHub. +Then on GitHub, click the 'Actions' tab at the top of your repository, then under 'All workflows' on the left click 'Combine PRs', and finally on the righthand side, click 'Run workflow'. ![Run workflow](/images/run.png?raw=true "Run workflow") # Customization -The workflow uses only the [actions/github-script](https://github.com/actions/github-script/) and [actions/checkout](https://github.com/actions/checkout/) actions published by GitHub. As you can see from the image you can easily set another branch prefix for matching, and choose whether to only include branches that are green (have the 'success' status on GitHub, e.g. from successful CI) - this is the default. If you don't run checks, then set this setting to false, since a PR with no checks will have a status of 'pending' rather than 'success'. You are also welcome to modify the code to your needs if you need more customization than that (for example it currently doesn't work with forks, only branches within the same repo). +The workflow uses only the [actions/github-script](https://github.com/actions/github-script/) and [actions/checkout](https://github.com/actions/checkout/) actions published by GitHub. +As you can see from the image you can easily set another branch prefix for matching, and choose whether to only include branches that are green (have the 'success' status on GitHub, e.g. from successful CI) - this is the default. +If you don't run checks, then set this setting to false, since a PR with no checks will have a status of 'pending' rather than 'success'. + +You are also welcome to modify the code to your needs if you need more customization than that (for example it currently doesn't work with forks, only branches within the same repo). # Limitations -This workflow merges the branches of the PRs together into a single branch using git's simple merge and automatic merge strategies. Unfortunately that means it has the same limitations as these merge strategies, so it will fail if two or more PRs have branches cannot be auto-merged due to a merge conflict - it will say something along the lines of "Auto-merge failed" or "Should not be doing an octopus" (see an example [here](https://github.com/hrvey/combine-prs-workflow/issues/2)). The way this will typically happen when updating dependencies is that different dependency updates end up modifying the same line in the .lock file (the file that ensures stability in exactly which versions of depencies are currently being used, when dependencies are defined in a broad enough way that multiple different versions could satisfy the constraints). This typically happens if they share some common third dependency - for example if some modular framework has components A and B, that both depend on C, then updating A and B independently might lead to also indirectly updating C to two different versions in the two branches, and that will prevent them from being mergable. The "correct" solution here is to add both dependencies together, then let the package manager resolve the dependencies to hopefully find a version of C to put in the .lock file that will satisfy both A and B. If you find yourself in need of this, then this workflow won't help you, and you should consier switching to a dependency update service that will update dependencies together like that (at the moment Dependabot does not, but Depfu and Renovate do). +This workflow merges the branches of the PRs together into a single branch using git's simple merge and automatic merge strategies. Unfortunately that means it has the same limitations as these merge strategies, so it will fail if two or more PRs have branches that cannot be auto-merged due to a merge conflict - it will say something along the lines of "Auto-merge failed" or "Should not be doing an octopus" (see an example [here](https://github.com/hrvey/combine-prs-workflow/issues/2)). +The way this will typically happen when updating dependencies is that different dependency updates end up modifying the same line in the `.lock` file (the file that ensures stability in exactly which versions of depencies are currently being used, when dependencies are defined in a broad enough way that multiple different versions could satisfy the constraints). +This typically happens if they share some common third dependency - for example if some modular framework has components A and B, that both depend on C, then updating A and B independently might lead to also indirectly updating C to two different versions in the two branches, and that will prevent them from being mergable. + +The "correct" solution here is to add both dependencies together, then let the package manager resolve the dependencies to hopefully find a version of C to put in the `.lock` file that will satisfy both A and B. +If you find yourself in need of this, then this workflow won't help you, and you should consider switching to a dependency update service that will update dependencies together like that (at the moment *Dependabot* does not, but *Depfu* and *Renovate* do).