1da44d091SHouston Putman= Working between Multiple Major versions 2da44d091SHouston Putman// Licensed to the Apache Software Foundation (ASF) under one 3da44d091SHouston Putman// or more contributor license agreements. See the NOTICE file 4da44d091SHouston Putman// distributed with this work for additional information 5da44d091SHouston Putman// regarding copyright ownership. The ASF licenses this file 6da44d091SHouston Putman// to you under the Apache License, Version 2.0 (the 7da44d091SHouston Putman// "License"); you may not use this file except in compliance 8da44d091SHouston Putman// with the License. You may obtain a copy of the License at 9da44d091SHouston Putman// 10da44d091SHouston Putman// http://www.apache.org/licenses/LICENSE-2.0 11da44d091SHouston Putman// 12da44d091SHouston Putman// Unless required by applicable law or agreed to in writing, 13da44d091SHouston Putman// software distributed under the License is distributed on an 14da44d091SHouston Putman// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15da44d091SHouston Putman// KIND, either express or implied. See the License for the 16da44d091SHouston Putman// specific language governing permissions and limitations 17da44d091SHouston Putman// under the License. 18da44d091SHouston Putman 19*4d023351SShai EreraWorking between multiple major versions of `lucene` is often a necessary part of committing code, due to backports and 20*4d023351SShai Ereratesting. For some versions, this is an even bigger issue because `8.x` and `9.x` use different build systems, ant and 21*4d023351SShai Ereragradle. Switching between these branches will result in many files left around that are not tracked by the other branch. 22da44d091SHouston PutmanEven when the build system between branches is the same, major refactoring can produce the same issues. 23da44d091SHouston PutmanThese orphaned files can impact the use of `precommit`, IntelliJ, and other tools. 24da44d091SHouston Putman 25da44d091SHouston Putman== Git Worktree 26da44d091SHouston Putman 27*4d023351SShai Ererahttps://git-scm.com/docs/git-worktree[Git worktree] is a feature of git that allows you to have different directories 28*4d023351SShai Ererastore separate checkouts of the same repository, at the same time. The git metadata is shared between the different 29*4d023351SShai Ereradirectories, so any remotes added or local commits made from one worktree are available to all other worktrees as well. 30da44d091SHouston Putman 31*4d023351SShai EreraFor Lucene, this allows us to have separate directories (worktrees) that manage the checkouts of `main` and `branch_8x` 32*4d023351SShai Erera(or any other major branch). One can make a commit on `main`, then easily switch directories and cherry-pick the commit 33*4d023351SShai Ereraonto `branch_8x` without having to worry about gradle or ant files. This setup also allows the commit to be tested on 34*4d023351SShai Erera`main` and `branch_8x` simultaneously. 35da44d091SHouston Putman 36da44d091SHouston Putman=== Setup 37da44d091SHouston Putman 38*4d023351SShai EreraWherever you store your source code, create a root folder for lucene. 39da44d091SHouston Putman 40*4d023351SShai Erera[source] 41*4d023351SShai Erera---- 42*4d023351SShai Ereramkdir lucene 43*4d023351SShai Erera---- 44da44d091SHouston Putman 45*4d023351SShai EreraThis folder is not a git folder. Instead, it will hold all of our lucene git checkouts. 46da44d091SHouston Putman 47*4d023351SShai Erera[source,bash] 48*4d023351SShai Erera---- 49*4d023351SShai Ereracd lucene 50*4d023351SShai Erera# main will be the main lucene checkout, that all worktrees stem from. 51*4d023351SShai Ereragit clone git@github.com:apache/lucene.git main 52*4d023351SShai Ereracd main 53da44d091SHouston Putman# For each branch that you want a separate directory created for, add a worktree 54*4d023351SShai Ereragit worktree add ../9x branch_9x 55*4d023351SShai Erera---- 56da44d091SHouston Putman 57da44d091SHouston Putman=== Using the Worktrees 58da44d091SHouston Putman 59da44d091SHouston PutmanIt's not necessary to create a worktree for every branch you are working on. 60*4d023351SShai EreraCreating repositories for each relevant major version is likely sufficient, because the differences between minor 61*4d023351SShai Ereraversions is likely not great enough to require a whole new folder. 62*4d023351SShai Erera 63*4d023351SShai EreraTherefore, most developers will only need two: main and the latest major version. Whenever working on a minor release 64*4d023351SShai Ererabranch, you can easily use the worktree that corresponds to the same major version. 65da44d091SHouston Putman 66da44d091SHouston PutmanIf you are using IntelliJ, you will likely want to load each of the worktrees as a separate project. 67da44d091SHouston PutmanThat way when you switch between them, IntelliJ will not have to re-build the project fully. 68