epugh commented on code in PR #1561: URL: https://github.com/apache/solr/pull/1561#discussion_r1165799913
########## dev-docs/git.adoc: ########## @@ -0,0 +1,240 @@ += Using Git + + +== Committing changes to Git + +*Totally incomplete, but we have to start somewhere. Please contribute!* + +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 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: + +* Only committers have the ability to commit to the official Git repository. +* IntelliJ and Eclipse have built-in Git integration +* There are visual tools that may be used as well. Mention here is not an endorsement, nor is it a complete list. + * SourceTree Free. + * SmartGit Licensed, not free. Well liked by at least some committers. + +== Useful Links + +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. + +* https://git-wip-us.apache.org/[Git at Apache] General Apache guidelines. +* https://github.com/dweiss/lucene-git-guides[Dawid's guide] From our very own Dawid Weiss. +* http://git.or.cz/course/svn.html[Git for SVN crash course] For people who know SVN but not Git. +* http://lmgtfy.com/?q=Git+beginners+guide[Let Me Google That For You] I've wanted to paste a link to LMGTFY for a long time... + + +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: + +[console] +---- +$ git config [--global] user.name <real-name> +$ git config [--global] user.email <email>@apache.org +---- + +*Is this really recommended?* + +[console] +---- +$ git config --global pull.rebase true +---- + +== Use a personal fork for branches + +For both contributors and committers, using personal forks to store feature branches is *strongly encouraged*. +You can fork the `apache/solr` repository through the Github UI. + +Once you have forked Solr, you can add it as a git "remote" locally so that you can push your branches there. +Then you can rename the official repo to "apache" to limit confusion. +If you want to name you local fork something other than "fork", then replace "fork" with the name you want to use. + +[console] +---- +$ git remote add fork <the git clone url that you get from github>" +$ git fetch fork +$ git remote rename origin apache +---- + + +== Working with Branches + +For almost all development on Solr, it is recommended to create a feature branch in your fork and a Pull Request (PR) in Github. + +=== 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. + +[console] +---- +$ git checkout apache/main +$ git pull +$ git checkout -b feature-name +$ git push fork feature-name +---- + +From now on, you can add files, commit and use `git push fork feature-name` whenever you want to upload your changes. + +=== Creating a PR + +Once your feature branch has been pushed to your fork, you can create a PR via the Github UI. +Go to https://github.com/apache/solr/pulls and click "New Pull Request". + +Since your feature branch lives on your fork, click "compare across forks". +Choose your fork for the "head repository", the option on the *right* of the arrow. +Then choose your feature branch right after it. + +Click "Create Pull Request", and choose a name that starts with "SOLR-####: ", so that your JIRA Issue will be linked to this PR. +Also be sure to click "Allow edits and access to secrets by maintainers", so that you can collaborate with other committers. + +=== Keeping your branch up-to-date with main + +While working on your branch, you should periodically bring it up to date with "main". +This will make eventual merging with main later simpler, because you resolve any conflicts as you go. + +The Github UI might allow you to do this, and if so it's perfectly safe to use that feature. +If the Github UI tells you to do it manually, *DO NOT follow their instructions, use the following*: + +[console] +---- +$ git fetch apache +$ git checkout <branch> # This is the feature branch you want to bring up-to-date +$ git merge apache/main +---- + +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: + +[console] +---- +$ git commit # Commit the fixes for conflicts. The message may be already populated, edit it as needed but it's not very important. +$ git push fork branch # Push the merged feature branch to your fork +---- + +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. Review Comment: I think we should remove this... It's easier to add new docs versus get rid of them... -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: issues-unsubscr...@solr.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@solr.apache.org For additional commands, e-mail: issues-h...@solr.apache.org
