目次

Version 12, last updated by Indrajit Raychaudhuri at Nov 28 20:17 UTC

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 branches are master (for scala 2.8) and master_2.7 (for scala 2.7), so any changes you make have to be committed to both.

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

  1. To simplify the process of keeping the 2.7.7 and 2.8.x branches in sync, we always start with development on the master_2.7 branch and then cherry-pick the commit to the master branch. To start, make sure you have the latest code by doing a “git pull” on the master_2.7 branch:
    git checkout master_2.7
    git pull
    
  2. Create a new local branch for your code that tracks the master_2.7 branch. Name the branch using the convention <your initials>-issue-<ticket number>. For example:
    git checkout master_2.7
    git checkout -t -b dcb-issue-75849
    
  3. Make your edits. Please add or modify existing Specs to provide test coverage for the change
  4. Run a “mvn clean install” from the root of the liftweb project to make sure that nothing breaks
  5. For any non-trivial change, please make sure the parts of the examples/example code that touch your change still work.
  6. Commit your changes. The commit log message should contain a short description of the work done, as well as a “Closes #<ticket number>” and, optionally, more description of the change. For example:
    Bent space-time to serve pages before the user requests them
    
    Closes #75849
    
    This involved a complete rewrite of LiftSession to interface with 
    the flux capacitor.
    
  7. If commits have been made against the master_2.7 branch since you started work, bring your branch up-to-speed by doing a “git rebase -i master_2.7”. Be aware that “git rebase” can be a destructive operation if you fail to complete (or abort) the process correctly. If you’re at all concerned or haven’t done this before, it can be a good practice to tag your branch using “git tag your_tag_name” prior to attempting the rebase.
  8. Create a diff file by doing a “git diff master > your_branch_name.diff” (the diff file is a temporary artifact)
  9. Go to http://reviewboard.liftweb.net/ and create a new review request. You’ll upload your diff file at this point. Provide a reasonable amount of detail for the various fields in the review request. In particular:
    1. Make sure you include the Ticket number (e.g., “Issue 123 – Made some changes”) in the title of the review board request
    2. Set the branch name to the name of your work branch
    3. Set the bugs field to the ticket number
    4. Enter at least a brief description of the work done
    5. Please describe what tests you’ve performed for a given ticket. Saying “Yes” for a test is not enough. Please describe what you did.
      Once you’re done editing, publish the review. This will send out emails to all of the reviewers on the request.
  10. Mark the ticket as “in test”
  11. Once there’s a general consensus with your reviewers that your code looks good, you can merge the code into the master_2.7. Start by doing another “git rebase -i master_2.7” in case any more changes have been made. Next, switch to the master_2.7. branch and merge in your changes:
    git checkout master_2.7
    git merge dcb-issue-75849
    
  12. Run a “mvn clean install” in the root of liftweb again to make sure that nothing has broken again
  13. Important: This step is important for master branch which is on Scala 2.8.x series. Starting Lift 2.2 Milestone 2, master builds on Scala 2.8.1. To verify that your commit does not break for Scala 2.8.0, run “mvn -f pom-280.xml verify” in addition to the above step. This applies Scala 2.8.0 specific patches to the build descriptors and verifies that nothing is broken for Scala 2.8.0 (in addition to Scala 2.8.1).
  14. Cherry-pick your commit into the master branch. You will need the Git hash of your WIP commit, which you can obtain with the “git show” command:
    $git show dcb-issue-75849
    commit 086b7c1b2ae2b3275af7300e0d29f39c44f0c8d9
    Author: ...
    $ git checkout master
    $ git cherry-pick 086b7c1b2ae2b3275af7300e0d29f39c44f0c8d9
    
  15. Run a “mvn clean install” in the root of liftweb again to make sure that nothing has broken again
  16. If everything is fine, push your changes (git push)
  17. Go back to review board and close the request as “submitted”
  18. Close ticket by marking as “Fixed” in ticketing system.
  19. At this point you can clean things up by deleting the diff file and your local work branch (git branch -d your_branch_name)

If you have a good working of 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.