Committing changes to Git

<!> Totally incomplete, but we have to start somewhere. Please contribute! <!>

Disclaimer Currently, we're still working out the preferred way of committing to Git, so this page is definitely a "work in progress". If you're a seasoned Git pro do not feel that what's written here is a requirement, but do please look it over and see if it's reasonably compatible.

There's been a lot of discussion about how to commit to the Git repo since we moved to using Git in early 2016. This page is intended for people new to Git or Lucene/Solr as a place to start. If you're totally new to Git or if you're a new committer, this should get you started.

NOTES:

There are about a zillion "how to use Git" links out there, here are a few links that are useful in this context. Except for Dawid's and Apache's pages, these are not associated with this project.

The goal here is to provide a super-simple guide without getting off into the all the possibilities, and it will certainly seem "too simple" to sophisticated users. We all have to start somewhere.

Git defaults

Here are some recommended defaults to configure Globally for Git:

git config [--global] user.name <real-name>
git config [--global] user.email <email>@apache.org

#Is this really recommended?
git config --global pull.rebase true

Simple commits

For simple commits for simple JIRAs for simple people, here are a few ways of going about it.

method 1

update your repo (perhaps with .gitconfig making this use rebasing)

Notes:

Backporting changes from trunk to 5x (6x sometime soon)

The usual recommendation is to "cherry pick".

<!> There has been some issue with Solr's CHANGES.txt file "cherry picking" all of the changes for trunk, so check this file especially <!>

Add patches to JIRA tickets or not?

<!> what is the consensus here? <!>

More sophisticated options for more sophisticated people

Working with Branches

Creating a Branch

Some feature work may be easier accomplished with a dedicated branch in Git. This allows several people to work together at once. Dawid's Git Page has details on how to create a branch and push it to the remote repository for others to pull and collaborate.

Preferred practice is to name your branch jira/solr-XXXXX (where "solr-XXXXX" is the JIRA ID), unless your feature does not yet have a single JIRA that's appropriate. In that case, you can use feature/<name>. If you name your branch in this way, commits to the branch will not pollute the comments of your JIRA issue.

Merging master with Your Branch

While working on your branch, you should periodically bring it up to date with "master". This will make eventual merging with master later simpler, because you resolve any conflicts as you go. To do this:

At this point, you likely have conflicts. You need to resolve those, and there are a number of ways to do that.

Once the conflicts have been resolved:

Git may prompt you to git rebase --continue, if conflicts are resolved, that should end up in the same place, of prompting you to git push your final changes to the remote repository.

You may want to consider doing git merge --squash master - this will merge all commits from master into a single commit locally. Then when you commit the changes to your branch, the branch history won't become polluted with commits that didn't originate from the branch.

Merging Your Branch with master

When your feature is complete, and you want to merge the branch to master, you definitely want to do a squash merge so all of the little commits you made in the branch don't pollute the project master history.

You may also want to merge with master only after doing one last merge of master to your branch. This will allow you to resolve conflicts in your branch before having to deal with them on master, and will make this process cleaner.

Be sure you have run ant precommit on your branch to find any unexpected problems. Best to resolve those on your branch instead of waiting for Jenkins builds to fail, or other committers to notice problems. Running any tests you can is also preferred.

To merge your branch with master:

Hopefully you have minimal or maybe no conflicts. If so, resolve them. When you're ready:

Before you push your changes to master, run ant precommit and tests again to check for anything unexpected.

That's it! Yeay!

IntelliJ notes

Git commit process (last edited 2017-05-10 20:51:05 by CassandraTargett)