mirror of https://github.com/apache/lucene.git
68 lines
3.2 KiB
Plaintext
68 lines
3.2 KiB
Plaintext
= Working between Multiple Major versions
|
|
// Licensed to the Apache Software Foundation (ASF) under one
|
|
// or more contributor license agreements. See the NOTICE file
|
|
// distributed with this work for additional information
|
|
// regarding copyright ownership. The ASF licenses this file
|
|
// to you under the Apache License, Version 2.0 (the
|
|
// "License"); you may not use this file except in compliance
|
|
// with the License. You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing,
|
|
// software distributed under the License is distributed on an
|
|
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
|
// KIND, either express or implied. See the License for the
|
|
// specific language governing permissions and limitations
|
|
// under the License.
|
|
|
|
Working between multiple major versions of `lucene` is often a necessary part of committing code, due to backports and
|
|
testing. For some versions, this is an even bigger issue because `8.x` and `9.x` use different build systems, ant and
|
|
gradle. Switching between these branches will result in many files left around that are not tracked by the other branch.
|
|
Even when the build system between branches is the same, major refactoring can produce the same issues.
|
|
These orphaned files can impact the use of `precommit`, IntelliJ, and other tools.
|
|
|
|
== Git Worktree
|
|
|
|
https://git-scm.com/docs/git-worktree[Git worktree] is a feature of git that allows you to have different directories
|
|
store separate checkouts of the same repository, at the same time. The git metadata is shared between the different
|
|
directories, so any remotes added or local commits made from one worktree are available to all other worktrees as well.
|
|
|
|
For Lucene, this allows us to have separate directories (worktrees) that manage the checkouts of `main` and `branch_8x`
|
|
(or any other major branch). One can make a commit on `main`, then easily switch directories and cherry-pick the commit
|
|
onto `branch_8x` without having to worry about gradle or ant files. This setup also allows the commit to be tested on
|
|
`main` and `branch_8x` simultaneously.
|
|
|
|
=== Setup
|
|
|
|
Wherever you store your source code, create a root folder for lucene.
|
|
|
|
[source]
|
|
----
|
|
mkdir lucene
|
|
----
|
|
|
|
This folder is not a git folder. Instead, it will hold all of our lucene git checkouts.
|
|
|
|
[source,bash]
|
|
----
|
|
cd lucene
|
|
# main will be the main lucene checkout, that all worktrees stem from.
|
|
git clone git@github.com:apache/lucene.git main
|
|
cd main
|
|
# For each branch that you want a separate directory created for, add a worktree
|
|
git worktree add ../9x branch_9x
|
|
----
|
|
|
|
=== Using the Worktrees
|
|
|
|
It's not necessary to create a worktree for every branch you are working on.
|
|
Creating repositories for each relevant major version is likely sufficient, because the differences between minor
|
|
versions is likely not great enough to require a whole new folder.
|
|
|
|
Therefore, most developers will only need two: main and the latest major version. Whenever working on a minor release
|
|
branch, you can easily use the worktree that corresponds to the same major version.
|
|
|
|
If you are using IntelliJ, you will likely want to load each of the worktrees as a separate project.
|
|
That way when you switch between them, IntelliJ will not have to re-build the project fully.
|