Use Git with Appkit

Table of Contents

Getting access to the project
Using the Fork-and-Branch Git workflow
Additional resources - great Git resources

At Lucidworks, we use GitHub for hosting and Git for version control of our code and customers' code. There are several good guides on the web to using Git detailed below, along with some high level instructions for getting started.

Getting access to the project

To gain access to a project, you must sign up for a free GitHub account. After you are signed up, contact Lucidworks Support and tell us who you are, your GitHub username, and which project you work on, and we can add you to the right project.

Using the Fork-and-Branch Git workflow

When working with multiple developers on a single codebase, we use a Fork-and-Branch model. This lets you create a copy of a repository, make your changes and then submit them back to the original repository for review by the owner before they are merged in.

GitHub Desktop App (Windows and Mac)

If you use the GitHub desktop application (details and install guide) there is a good Github guide on how forking with the GitHub desktop app works.

Command Line (Windows and Mac)

If you use the command-line git tools then the “fork and branch” workflow process is documented well in this blog post:

The article above covers it really well, but at a high level the process is as follows:

Fork a GitHub repository.
Clone the forked repository to your local system.
Add a Git remote for the original repository.
Create a feature branch in which to place your changes.
Make your changes to the new branch.
Commit the changes to the branch.
Push the branch to GitHub.
Open a pull request from the new branch to the original repo.
Keeping Your Fork in Sync.

If you are stuck, search for a specific command in the Pro Git book; it is a useful resource.

Forking a GitHub Repository

Forking a repository is really straightforward:

Make sure you’re logged into GitHub with your account. Find the GitHub repository with which you’d like to work.

Click the Fork button on the upper right-hand side of the repository’s page. That’s it — you now have a copy of the original repository in your GitHub account.

Making a local clone

Even though you have a copy of the original repository in your GitHub account, you must copy it (clone it) locally so you can work on it. Navigate to the forked repository on github.com (this is the copy of the original repository residing in your GitHub account) and look on the right-hand side of the web page. You should see an area that is labeled “HTTPS clone URL”. Simple copy the URL there and use as follows:

git clone https://github.com/username/projectname.git

Here, username is your GitHub username and projectname is the specific name of the project (GitHub provides you the URL to copy and paste for ease).

Git will copy down the repository, both contents and commit history, to your system. Git will also add a Git remote named origin that points back to the forked repository in your GitHub account.

Adding a Git Remote

Git already added a Git remote named origin to the clone of the Git repository on your system, and this will let you push changes back up to the forked repository in your GitHub account using git commit (to add commits locally) and git push.

To use the “fork and branch” workflow, you’ll must add a Git remote pointing back to the original repository (the one you forked on GitHub).

You’d want to add a Git remote that points back to the original repository, like this:

git remote add upstream https://github.com/twigkit/projectname.git

Of course, you’d want to replace the URL after git remote add upstream with the appropriate clone URL for the original project repository.

Keeping Your Fork in Sync

Your forked repository does not stay in sync automatically - you must take care of this yourself - it is good practice to do this before you start work to pull in changes from other developers. To ensure your code has the latest upstream code changes, first make sure you are on your local master branch:

git checkout master

Then either pull the latest changes in - these commands pull (fetch and merge) the most recent changes from the upstream repository, and pushes them back to your repository:

git pull upstream master
git push origin master

Or explicitly fetch and merge the most recent changes from the upstream repository:

git fetch upstream
git merge upstream/master
git push origin master

Working with feature branches

The master branch is the master copy of the code. When working on individual features, it is better to work in branches. Using branches, you can switch between different development tasks easily mid-flow.

Create a new branch

git checkout -b <new branch name>

For example, suppose you are working on ISSUE-1234. Then before doing any code changes, make sure you create a new feature branch like so:

git checkout -b ISSUE-1234

Commit changes

See what files you have changed and what is queued up to commit:
```
git status
```
Add some changes you have made to commit:
```
git add </path/to/filename>
```
Make your changes and then commit the changes to the branch:
```
git commit -m 'short descriptive note about my changes'
```

Push changes back to your repository

When you’re ready to commit your changes, push those changes up to the corresponding feature branch on your remote fork. This does not push the changes back to Appkit - just to your forked copy:

git push -u origin <new branch name>

See https://help.github.com/articles/pushing-to-a-remote/ and https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes.

Other useful commands are git branch (lists what branches you have created) and git remote -v (lists what remote repositories you are linked to).

Sending changes back to the master repository - opening a Pull Request

When your feature branch is ready to have its changes brought into the master branch, you must go to your GitHub fork and issue a new pull request from that feature branch. If the branch does not already exist in GitHub, a pull request will automatically be created when you push the new branch up to your repository - GitHub will prompt you to create a pull request when you view the repo online (I’m assuming you’re using your browser and not the GitHub native apps). The maintainers of the original project can use this pull request to pull your changes across to their repository and, if they approve of the changes, merge them into the main repository. See this guide on how to create a pull request in GitHub for more details.

It is good practice to ensure the pull request has a clear description of what it entails, and it should refer back to the issue that is being resolved in either the title or the description.

Code review

After you have created the pull request, you should assign it to a colleague for peer review. If any issues are identified during the review, the reviewer can add code comments, and assign the pull request back to you to fix. After the pull request has passed its code review, the reviewer can assign the pull request to a dedicated merge master who can do the final merge.

Milestones and releases

GitHub lets you tag your work and keep track of which tasks should be completed by specific milestones or releases. You might also want to consider following this practice to ensure development work on your codebase is sufficiently prioritized.

Additional resources - great Git resources

The best reference on the web is the git SCM book - https://git-scm.com/book/en/v2 - covers everything you must know about Git - a great reference if you are stuck or if you are getting started, a simplified Git Guide.