This is an automated email from the ASF dual-hosted git repository.
visortelle pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 30f618024318 Add contributor documentation for setting up git
mergetool (#823)
30f618024318 is described below
commit 30f6180243188b886e64ba5d63c122e86dfdfd6b
Author: Lari Hotari <[email protected]>
AuthorDate: Tue Mar 5 12:23:04 2024 +0200
Add contributor documentation for setting up git mergetool (#823)
* Add contributor documentation for setting up git mergetool
* Add recommendation of using a mergetool
* Add more tips
---
contribute/release-process.md | 2 +
contribute/setup-building.md | 2 +-
contribute/setup-mergetool.md | 102 ++++++++++++++++++++++++++++++++++++++++++
sidebarsDevelopment.js | 1 +
4 files changed, 106 insertions(+), 1 deletion(-)
diff --git a/contribute/release-process.md b/contribute/release-process.md
index 76f84fa967d9..fc70646ca837 100644
--- a/contribute/release-process.md
+++ b/contribute/release-process.md
@@ -105,6 +105,8 @@ For patch releases, the tag is like `2.3.1`.
### Cherry-picking changes scheduled for the release
+Before proceeding, ensure that you have [set up a Git
mergetool](setup-mergetool.md). This tool is essential for resolving merge
conflicts that may arise during the cherry-picking process.
+
Use a search such as `is:merged is:pr label:release/3.0.3
-label:cherry-picked/branch-3.0` to search for merged PRs that are scheduled
for the release, but haven't yet been cherry-picked.
It is necessary to handle cherry-picks in the same order as they have been
merged in the master branch. Otherwise there will be unnecessary merge
conflicts to resolve.
diff --git a/contribute/setup-building.md b/contribute/setup-building.md
index fd3d7718176f..6fbcce640b9f 100644
--- a/contribute/setup-building.md
+++ b/contribute/setup-building.md
@@ -7,7 +7,7 @@ title: Setup and building
| Dependency | Description
|
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Git | The source code of Pulsar is hosted on GitHub as a git
repository. To work with the git repository, please [install
git](https://git-scm.com/downloads).
|
+| Git | The source code of Pulsar is hosted on GitHub as a git
repository. To work with the git repository, please [install
git](https://git-scm.com/downloads). We highly recommend that you also [set up
a Git mergetool](setup-mergetool.md) for resolving merge conflicts. |
| JDK | The source code of Pulsar is primarily written in Java.
Therefore, you need a working Java Development Kit (JDK) to build it. Pulsar
requires [JDK 17](https://adoptium.net/temurin/releases/?version=17) to build. |
| Maven | The source code of Pulsar is managed by [Apache
Maven](https://maven.apache.org/) The required Maven version is 3.6.1+.
|
| Zip | The build process requires Zip as a utility tool.
|
diff --git a/contribute/setup-mergetool.md b/contribute/setup-mergetool.md
new file mode 100644
index 000000000000..f0f2066fefb1
--- /dev/null
+++ b/contribute/setup-mergetool.md
@@ -0,0 +1,102 @@
+---
+id: setup-mergetool
+title: Setting up Git mergetool
+---
+
+## Merge conflict resolution tooling
+
+For Apache Pulsar core developers, handling git merge conflict resolution is
necessary.
+To efficiently resolve merge conflicts, setting up tools that assist in
visualizing these conflicts and resolving them is essential.
+
+For developers starting to use automated tools to resolve merge conflicts
during cherry-picking, IntelliJ is a recommended option. It offers excellent
tooling, but its integration with a command-line workflow is not seamless. It
performs well when you initiate the cherry-picking process in IntelliJ and
handle the merge conflict resolution within the same environment. However,
resolving a merge conflict often involves multiple steps, including reverting
and amending changes until a satisf [...]
+
+For more advanced users who use `git` on the command line, setting up the `git
mergetool` is recommended.
+Here's an example of how to set up `kdiff3` as a mergetool.
+
+### kdiff3 configuration on MacOS
+
+Install `kdiff3`'s cask version with `brew`:
+```shell
+# important! install the cask version of kdiff3
+brew install --cask kdiff3
+```
+
+Configure `kdiff3` as the mergetool and difftool of git
+```shell
+git config --global mergetool.kdiff3.path
/Applications/kdiff3.app/Contents/MacOS/kdiff3
+git config --global mergetool.kdiff3.args '$base $local $other -o $output'
+git config --global mergetool.kdiff3.trustExistCode false
+git config --global merge.tool kdiff3
+git config --global difftool.kdiff3.path
/Applications/kdiff3.app/Contents/MacOS/kdiff3
+git config --global difftool.kdiff3.args '$base $local $other -o $output'
+git config --global difftool.kdiff3.trustExistCode false
+git config --global diff.guitool=kdiff3
+```
+
+### kdiff3 configuration on Linux
+
+Install `kdiff3` from your package manager. For example, on Ubuntu:
+```shell
+sudo apt install kdiff3
+```
+
+Configure `kdiff3` as the mergetool and difftool of git
+```shell
+git config --global mergetool.kdiff3.path /usr/bin/kdiff3
+git config --global merge.tool kdiff3
+git config --global difftool.kdiff3.path /usr/bin/kdiff3
+git config --global diff.guitool=kdiff3
+```
+
+### Using the mergetool kdiff3
+
+If any merge conflicts arise after a cherry-pick, merge, or rebase, you should
run `git mergetool` to resolve them.
+You can run `git mergetool` anytime, as the command will return when there are
no conflicts to resolve.
+
+The `kdiff3` tool isn't the most user-friendly tool, and it takes time to get
accustomed to its workings.
+There's commentary on mergetools [in this blog
post](https://www.eseth.org/2020/mergetools.html) that could help
+you understand what the tools do and how merges are visualized in different
tools.
+One of the advantages of `kdiff3` is that it contains a custom merge algorithm
which can resolve some conflicts
+without requiring a choice. In some cases, there may be chances for mistakes,
but these are rare and could also occur when
+manually choosing the resolution. The resolution will need to be verified in
any case.
+
+Tips for Using `kdiff3`
+- When the merge conflict resolution process begins, a view with three panes
and a split pane at the bottom of the window will appear.
+ - The left pane displays the diff from the common version of the file.
This can be confusing and is often not very useful. You can hide it by
deselecting "Window -> Show Window A".
+ - The middle pane shows the local version.
+ - The right pane shows the remote version.
+ - The bottom pane is the output, which is the result of the merge. You can
also make manual edits in this pane to resolve conflicts manually.
+- It's beneficial to learn how to navigate to the next and previous merge
conflict and how to choose the resolution using keyboard shortcuts.
+ - On MacOS, you may need to remap some of the keyboard shortcuts to
improve usability. This is especially necessary when using an external keyboard.
+
+### Git revert and commit amending tooling
+
+Resolving merge conflicts can sometimes be more complex with merge tools than
simply reverting some changes and modifying the original source code in an IDE.
This process may involve multiple steps, including reverting and amending
changes to the merge commit. The merge commit should also incorporate the
necessary changes for backporting.
+In many cases, it is also necessary to fix the import statements in an IDE and
amending those changes to the merge commit.
+
+For this purpose, the `git gui` tool is excellent. It allows for partial
reverts to previous commits and makes it easy to amend additional changes to
the latest commit, all with clear visualization.
+
+Installing the `git gui` tool:
+
+```shell
+# on MacOS
+brew install git-gui
+```
+
+```shell
+# on Linux install "git-gui" from your package manager, example of Ubuntu
+sudo apt install git-gui
+```
+
+There are many tools available for this purpose, but `git gui` is one of the
simplest and most effective.
+
+### Using IntelliJ for cherry-picking and merge conflict resolution.
+
+- [Cherry-pick separate
commits](https://www.jetbrains.com/help/idea/apply-changes-from-one-branch-to-another.html#cherry-pick)
+- [Resolving Git Merge Conflicts: The Easy
Way](https://www.youtube.com/watch?v=mSfq1SoMocg)
+
+### Useful links
+
+- [Comparison of git mergetools](https://www.eseth.org/2020/mergetools.html)
+- [Comparison of file comparison
tools](https://en.wikipedia.org/wiki/Comparison_of_file_comparison_tools#General)
+- [Git GUI Clients](https://git-scm.com/downloads/guis)
\ No newline at end of file
diff --git a/sidebarsDevelopment.js b/sidebarsDevelopment.js
index 8b0bc614cd68..4772676a2dc9 100644
--- a/sidebarsDevelopment.js
+++ b/sidebarsDevelopment.js
@@ -8,6 +8,7 @@ const sidebars = {
items: [
'setup-building',
'setup-ide',
+ 'setup-mergetool',
'setup-debugging'
]
},
