docs: Add section to git doc about fixing problems #1643
Conversation
In case something goes wrong with git history, users should have the information how to fix problems.
|
This is a follow-up from the git-fixing session with @ZoranCutura |
|
The created documentation from the pull request is available at: docu-html |
|
|
||
| - Multiple, consecutive commits by the same author, like "draft one", "after review", "forgotten in previous commit". | ||
| Such commits should be squashed into a single commit, with a well-written commit message. | ||
| - Merges from the main branch into a feature branch. |
There was a problem hiding this comment.
actually both examples are only relevant for non squash commits, which are not recommended anyway ;-)
There was a problem hiding this comment.
Though not recommended, anybody getting onboarded should know directly how to commit and how to rebase (instead of merging with main, which is provided in github as a single button press), otherwise they may learn hard before a pull-request.
So my quest is rather, how do we make sure ev1 can avoid tricky squashing after some 3 months working on a branch / pull-request with multiple authors.
There was a problem hiding this comment.
Don't work 3 months on a branch with multiple authors?
Seriously. I strongly advertise for merging multiple times per day.
There was a problem hiding this comment.
Well that actually was the case with all feature requests, that were started early in spring and are being merged right now. So it seems to be a usual working construct at least for bigger contributions, such as feature requests that also demanded quite some work to be done before they can be accepted.
Should we have some recommendations for such situations, or maybe recommendations on how to avoid them?
There was a problem hiding this comment.
I added something for this: strategies how to avoid or deal with long-lived feature branches.
| - Multiple, consecutive commits by the same author, like "draft one", "after review", "forgotten in previous commit". | ||
| Such commits should be squashed into a single commit, with a well-written commit message. | ||
| - Merges from the main branch into a feature branch. | ||
| Instead, the feature branch should be rebased on top of the main branch. |
There was a problem hiding this comment.
Not on collaborative branches with multiple authors
| Afterwards, the (now cleaned-up) branch can be force-pushed to the remote repository. | ||
| This works also if there is already a pull-request open for this branch. | ||
|
|
||
| The Git Documentation contains `a well-written section <https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History>`_ about "rewriting history". |
There was a problem hiding this comment.
That section does not cover simple rebases, that would be https://git-scm.com/book/en/v2/Git-Branching-Rebasing and merging at https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging or maybe even just branching in general at https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell
We need to be careful not to write yet another (and very incomplete) git tutorial here.
There was a problem hiding this comment.
That is correct, so I did not link it. This section is only about the case of "repairing an already botched history". Hence interactive rebase, or "step by step cherry picking onto new branch" are the right strategies.
docs/contribute/general/git.rst
Outdated
| The Git Documentation contains `a well-written section <https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History>`_ about "rewriting history". | ||
| However, to be fair, this is not simple when you do it for the first time. | ||
| The most efficient approach is to do this together with someone experienced in Git. | ||
| Such a pairing session can show you how to "think Git". |
There was a problem hiding this comment.
| Such a pairing session can show you how to "think Git". | |
| Such a pairing session, let's go crazy and call it pair programming, can show you how to "think Git". |
😆
There was a problem hiding this comment.
I actually added a link to "pair programming" since actually, not everyone will know that concept.
|
@opajonk @AlexanderLanin any ideas how to get that closed (meeting ....)? |
Yes this was entirely my fault. I "almost forgot" about this. I have it now properly in my todo list and will follow up. |
Since this is frequently a source of problems, let's have a short description and add strategies how to deal with this up-front.
Actually, this second strategy is the one that Zoran and I used for the specific feature branch that triggered the creation of this PR in the first place.
| content in a separate file until the work is done. Then, only in a last step integrate the | ||
| new content into the structure which exists in the main branch. | ||
| 3. Accept the fact that conflicts may arise and deal with them when they occur. | ||
|
|
There was a problem hiding this comment.
I'm not sure if "merge frequently" is the same as 1?
There was a problem hiding this comment.
Not sure what you mean... 1 says "merge frequently into main", but for that you must be able to do that --> split work into smaller units. This may not be always possible, hence there are strategies 2 and 3 as well.
3 is not "merge frequently into main"; if anything, it is "merge frequently into the feature branch". However, you can also deal with the conflicts at the end, once. It may or may not be less work.
|
Co-authored-by: Alexander Lanin <alex@lanin.de> Signed-off-by: Oliver Pajonk <oliver@pjnk.de>
In case something goes wrong with git history, users should have the information how to fix problems.