Lift

This is a short guide to how we add new features or bugfixes to Liftweb. Two important things to note:

1. If you want to be able to commit code, you must have first signed an IP assignment form and been added as a committer to the project on GitHub.
2. The current working branch is master.

When you want to fix a bug or add a new feature:

Prepare master branch

If this is your first time, you’ll need to clone the Lift repo. If you have an existing clone, make sure it’s up-to-date:

git checkout master
git fetch
git rebase origin/master

Create a local branch

This is where you’ll make your edits.

git checkout -b <branch_name>

That will create a new branch and make it your current working branch. Typically branches are named using this convention: [initials]_issue_[ticket_ number]. For example: dpp_issue_99.

Commit code

Once you’ve finished writing and testing your code you’ll need to commit it and submit a pull request.

git add -u # adds all modified files currently under version control
git add path/to/file # do for each remaining new file
git commit -m "Issue 99 - Made a great bug fix."

Push branch to GitHub

Make sure you add tracking to your branch. It’s required to make a pull-request.

git push -u <branch_name>

The -u option automatically sets up tracking for you.

Issue pull request

Normally, when you make a pull request, github will create a new ticket for it. We prefer adding it to an existing ticket. This currently requires using hub

Once you have that installed, just run the following:

hub pull-request -i <ticket_number>

That will attach the pull request to the existing ticket and allow others to review it. When you get some +1’s or if a bunch of days pass and nobody reviews your code, then merge it.

Note: hub uses the GitHub API v2 which uses your GitHub token for authentication. So, you’ll need that configured in your .gitconfig file. See GitHub Help for more info. v2 is deprecated so this will probably change at some point.

Merge changes into master

Follow these steps to merge your changes into the master branch. It’s important to use rebase instead of merge to keep the changelog clean.

First thing we want to do is make sure the master branch is up-to-date.

git checkout master
git fetch
git rebase origin/master

Now, go back to your branch and make sure any changes that were added to master are rebased into your branch.

git checkout <branch_name>
git rebase master

Now, merge your branch into your local master

git checkout master
git merge <branch_name>

Push your master branch to GitHub.

git push origin master

Clean up local and remote branches.

git branch -d <branch_name>
git push origin :<branch_name>

Close the ticket on GitHub and you’re done.

If you have a good working knowledge of Git and you prefer alternatives to these commands, please feel free to do so. In general, try to avoid cluttering the commit log with “merged branch” messages and intermediate commit entries if possible.