diff options
author | Warner Losh <imp@FreeBSD.org> | 2023-02-08 18:46:34 +0000 |
---|---|---|
committer | Warner Losh <imp@FreeBSD.org> | 2023-03-31 10:54:49 +0000 |
commit | 9a4dfb1818c6cc5607e085a28ae256cefca5aede (patch) | |
tree | d3b9af99edf439af8927d50619d0e4ae619b8eae /documentation/content/en/articles/committers-guide | |
parent | 8a25677c39aa9eda7c3fedc6ad6b4acef061ada7 (diff) |
Diffstat (limited to 'documentation/content/en/articles/committers-guide')
-rw-r--r-- | documentation/content/en/articles/committers-guide/_index.adoc | 99 |
1 files changed, 63 insertions, 36 deletions
diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index 935541a992..0b4f116cba 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -805,15 +805,14 @@ Could not apply 646e0f9cda11... no color ls which looks scary. If you bring up an editor, you will see it is a typical 3-way merge conflict resolution that you may be familiar with from other source code systems (the rest of ls.c has been omitted): [source,shell] -.... -<<<<<<< HEAD -#ifdef COLORLS_NEW -#include <terminfo.h> -======= -#undef COLORLS -#ifdef COLORLS -#include <termcap.h> ->>>>>>> 646e0f9cda11... no color ls + <<<<<<< HEAD + #ifdef COLORLS_NEW + #include <terminfo.h> + ======= + #undef COLORLS + #ifdef COLORLS + #include <termcap.h> + >>>>>>> 646e0f9cda11... no color ls .... The new code is first, and your code is second. The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then delete the old changes: @@ -1181,56 +1180,84 @@ Because the current policy recommends against using merges, if the upstream Free Regular `git rebase` or `git pull --rebase` doesn't know how to rebase a merge commit **as a merge commit**, so instead of that you would have to recreate the commit. -The easiest way to do this would be to create a side branch with the **contents** of the merged tree: - -[source,shell] -.... -% cd ../src -% git fetch freebsd -% git checkout -b merge_result -% git merge freebsd/main -.... - -Typically, there would be no merge conflicts here (because developers tend to work on different components). -In the worst case scenario, you would still have to resolve merge conflicts, if there was any, but this should be really rare. +The following steps should be taken to easily recreate the merge commit as if `git rebase --merge-commits` worked properly: +* cd to the top of the repo +* Create a side branch `XXX` with the **contents** of the merged tree. +* Update this side branch `XXX` to be merged and up-to-date with FreeBSD's `main` branch. +** In the worst case scenario, you would still have to resolve merge conflicts, if there was any, but this should be really rare. +** Resolve conflicts, and collapse multiple commits down to 1 if need be (without conflicts, there's no collapse needed) +* checkout main +* create a branch `YYY` (allows for easier unwinding if things go wrong) +* Re-do the subtree merge +* Instead of resolving any conflicts from the subtree merge, checkout the contents of XXX on top of it. +** The trailing '.' is important, as is being at the top level of the repo. +** Rather than switching branches to XXX, it splats the contents of XXX onto of the repo +* Commit the results with the prior commit message (the example assumes there's only one merge on the XXX branch). +* Make sure the branches are the same. +* Do whatever review you need, including having others check it out if you think that's needed. +* Push the commit, if you 'lost the race' again, just redo these steps again (see below for a recipe) +* Delete the branches once the commit is upstream. They are throw-a-way. -Now, checkout `freebsd/main` again as `new_merge`, and redo the merge: +The commands one would use, following the above example of mtree, would be like so (the `#` starts a comment help line commands to descriptions above): [source,shell] .... -% git checkout -b new_merge freebsd/main -% git subtree merge -P contrib/mtree vendor/NetBSD/mtree +% cd ../src # CD to top of tree +% git checkout -b XXX # create new throw-away XXX branch for merge +% git fetch freebsd # Get changes from upstream from upstream +% git merge freebsd/main # Merge the changes and resolve conflicts +% git checkout -b YYY freebsd/main # Create new throw-away YYY branch for redo +% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge +% git checkout XXX . # XXX branch has the conflict resolution +% git commit -c XXX~1 # -c reuses the commit message from commit before rebase +% git diff XXX YYY # Should be empty +% git show YYY # Should only have changes you want, and be a merge commit from vendor branch .... -Instead of resolving the conflicts, perform this instead: - +Note: if things go wrong with the commit, you can reset the `YYY` branch by reissuing the checkout command that created it with -B to start over: [source,shell] .... -% git checkout merge_result . +% git checkout -B YYY freebsd/main # Create new throw-away YYY branch if starting over is just going to be easier .... -Which will overwrite the files with conflicts with the version found in `merge_result`. +==== Pushing the changes + +Once you think you have a set of changes that are good, you can push it to a fork off GitHub or GitLab for others to review. +One nice thing about Git is that it allows you to publish rough drafts of your work for others to review. +While Phabricator is good for content review, publishing the updated vendor branch and merge commits lets others check the details as they will eventually appear in the repository. -Examine the tree against `merge_result` to make sure that you haven't missed deleted files: +After review, when you are sure it is a good change, you can push it to the FreeBSD repo: [source,shell] .... -% git diff merge_result +% git push freebsd YYY:main # put the commit on upstream's main branch +% git branch -D XXX # Throw away the throw-a-way branches. +% git branch -D YYY .... -==== Pushing the changes +Note: I used `XXX` and `YYY` to make it obvious they are terrible names and should not leave your machine. +If you use such names for other work, then you'll need to pick different names, or risk losing the other work. +There is nothing magic about these names. +Upstream will not allow you to push them, but never the less, please pay attention to the exact commands above. +Some commands use syntax that differs only slightly from typical uses and that different behavior is critical to this recipe working. -Once you are sure that you have a set of deltas you think is good, you can push it to a fork off GitHub or GitLab(TM) for others to review. -One nice thing about Git is that it allows you to publish rough drafts of your work for others to review. -While Phabricator is good for content review, publishing the updated vendor branch and merge commits lets others check the details as they will eventually appear in the repository. +==== How to redo the if need be -After review, when you are sure it is a good change, you can push it to the FreeBSD repo: +If you've tried to do the push in the previous section and it fails, then you should do the following to 'redo' things. +This sequence keeps the commit with the commit message always at XXX~1 to make committing easier. [source,shell] .... -% git push freebsd HEAD:main +% git checkout -B XXX YYY # recreate that throw-away-branch XXX and switch to it +% git merge freebsd/main # Merge the changes and resolve conflicts +% git checkout -B YYY freebsd/main # Recreate new throw-away YYY branch for redo +% git subtree merge -P contrib/mtree vendor/NetBSD/mtree # Redo subtree merge +% git checkout XXX . # XXX branch has the conflict resolution +% git commit -c XXX~1 # -c reuses the commit message from commit before rebase .... +Then go check it out as above and push as above when ready. + === Creating a new vendor branch There are a number of ways to create a new vendor branch. |