This is an automated email from the ASF dual-hosted git repository.
lhotari 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 b022f93c96ec Add more git tips (#824)
b022f93c96ec is described below
commit b022f93c96ec2e8eb2e499ca8dff99a1fc774770
Author: Lari Hotari <[email protected]>
AuthorDate: Wed Jun 5 14:20:42 2024 +0300
Add more git tips (#824)
---
contribute/release-process.md | 2 +-
contribute/setup-building.md | 2 +-
contribute/{setup-mergetool.md => setup-git.md} | 114 +++++++++++++++++++++---
docusaurus.config.js | 13 ++-
preview.sh | 7 ++
sidebarsDevelopment.js | 2 +-
6 files changed, 124 insertions(+), 16 deletions(-)
diff --git a/contribute/release-process.md b/contribute/release-process.md
index 830cbf77aae7..0167fd8c608c 100644
--- a/contribute/release-process.md
+++ b/contribute/release-process.md
@@ -119,7 +119,7 @@ Note that you should also stop the workflow for previous
Pulsar versions that ar
### 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.
+Before proceeding, ensure that you have [set up a Git
mergetool](setup-git.md#mergetool). 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 6fbcce640b9f..889ab6ee5f6c 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). We highly recommend that you also [set up
a Git mergetool](setup-mergetool.md) for resolving merge conflicts. |
+| 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-git.md#mergetool) 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-git.md
similarity index 60%
rename from contribute/setup-mergetool.md
rename to contribute/setup-git.md
index cf7b425f3a02..dd577fc20127 100644
--- a/contribute/setup-mergetool.md
+++ b/contribute/setup-git.md
@@ -1,16 +1,102 @@
---
-id: setup-mergetool
-title: Setting up Git mergetool
+id: setup-git
+title: Setting up Git for maintenance of Pulsar
---
-## Merge conflict resolution tooling
+## Git configuration
-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.
+### Tooling
+
+#### Install `gh` command line tool for GitHub
+
+Installing with `brew`, for other package managers, follow instructions at
https://cli.github.com/.
+
+```shell
+brew install gh
+```
+
+After installing authenticate to GitHub
+
+```shell
+gh auth login
+```
+
+#### Optional: Install `tig` command line UI for git
+
+`tig` is handy for viewing the git log and it can also be used for staging
files and assisting with `git` command line usage.
+
+MacOS
+
+```shell
+brew install tig
+```
+
+Ubuntu Linux
+
+```shell
+sudo apt install tig
+```
+
+There are also other more feature rich alternatives such as
[`gitui`](https://github.com/extrawurst/gitui) or
[`lazygit`](https://github.com/jesseduffield/lazygit).
+
+### Git configuration tuning
+
+Increase default renamed file detection limit with mergetool and difftool
+
+```shell
+git config --global merge.renameLimit 2048
+git config --global diff.renameLimit 2048
+```
+
+Enable [rerere](https://git-scm.com/book/en/v2/Git-Tools-Rerere), "reuse
recorded resolution" for Git.
+
+```shell
+git config --global rerere.enabled true
+```
+
+Notice! In some cases, it might be useful to disable rerere after an invalid
merge resolution. In that case you will need to use `git rerere forget file` to
forget the merge result.
+
+### Checking out each Pulsar maintenance branch in a separate working directory
+
+For maintaining Pulsar, it is handy to have all maintenance branches checked
out in separate working directories
+
+Check out Pulsar repository
+
+```shell
+# assuming that GitHub autentication has been configured with "gh auth login"
+git checkout https://github.com/apache/pulsar
+cd pulsar
+# add your forked repository as a remote, you can have your own preferences
how to name the remotes
+git remote add forked https://github.com/your_github_id/pulsar
+```
+
+Add separate working directories that share the local git repository
+
+```shell
+for branch in branch-3.3 branch-3.2 branch-3.1 branch-3.0; do
+ git worktree add ../pulsar-$branch $branch
+done
+```
+
+After this you would have these directories in the same level as the original
checked out `pulsar` directory:
+
+```
+pulsar-branch-3.3
+pulsar-branch-3.2
+pulsar-branch-3.1
+pulsar-branch-3.0
+```
+
+There a limitation that each branch can only be checked out in one working
directory at a time. If that becomes a problem you could temporarily detach the
current branch in the working directory with `git commit --detach HEAD` command.
+
+## Merge conflict resolution tooling {#mergetool}
+
+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.
+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
@@ -22,6 +108,7 @@ 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'
@@ -35,15 +122,16 @@ git config --global diff.guitool kdiff3
`kdiff3` version 1.11.1 contains [bug
#487338](https://bugs.kde.org/show_bug.cgi?id=487338). You might want to
install kdiff3 1.10.7 from https://download.kde.org/stable/kdiff3/ until the
issue is resolved.
-
### 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
@@ -64,13 +152,14 @@ without requiring a choice. In some cases, there may be
chances for mistakes, bu
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.
+ - 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.
+ - 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
@@ -93,6 +182,7 @@ 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)
diff --git a/docusaurus.config.js b/docusaurus.config.js
index 01aeb408d19c..c59a2e65a02d 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -454,6 +454,17 @@ module.exports = {
],
],
plugins: [
+ [
+ '@docusaurus/plugin-client-redirects',
+ {
+ redirects: [
+ {
+ from: '/contribute/setup-mergetool',
+ to: '/contribute/setup-git',
+ },
+ ],
+ },
+ ],
'docusaurus-plugin-image-zoom',
[
"content-docs",
@@ -498,7 +509,7 @@ module.exports = {
routeBasePath: "client-feature-matrix",
sidebarPath: false,
}),
- ],
+ ]
],
scripts: [
{ src: "/js/sine-waves.min.js", async: true },
diff --git a/preview.sh b/preview.sh
index 3ec43eebb98b..8c25e7d75f64 100755
--- a/preview.sh
+++ b/preview.sh
@@ -7,5 +7,12 @@ BUILD_VERSIONS=$BUILD_VERSIONS"]"
echo $BUILD_VERSIONS >.build-versions.json
+if ! command -v yarn &>/dev/null; then
+ echo "yarn is not available. yarn comes with corepack, with homebrew you
can install it by running:"
+ echo "brew install corepack || brew link corepack"
+ echo "corepack enable"
+ exit 1
+fi
+
yarn install
yarn start
diff --git a/sidebarsDevelopment.js b/sidebarsDevelopment.js
index 4772676a2dc9..2e7567ddb8ef 100644
--- a/sidebarsDevelopment.js
+++ b/sidebarsDevelopment.js
@@ -8,7 +8,7 @@ const sidebars = {
items: [
'setup-building',
'setup-ide',
- 'setup-mergetool',
+ 'setup-git',
'setup-debugging'
]
},
